/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact be6a431e128b831df7d62fc48b7ce2043f55cf90:


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 36 20 32 30 30 38 2f  in,v 1.296 2008/
05f0: 30 33 2f 32 30 20 31 34 3a 30 33 3a 32 39 20 64  03/20 14:03:29 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 64 61 74 61 62 61 73 65 20  lar.** database 
11210 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73 75 70 70  connection, supp
11220 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
11230 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  t argument..** T
11240 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11250 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
11260 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
11270 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
11280 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
11290 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
112a0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
112b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
112c0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
112d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
112e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
112f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
11300 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
11310 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
11320 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
11330 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
11340 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
11350 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
11360 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
11370 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11380 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
11390 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
113a0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
113b0 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
113c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
113d0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
113e0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f  urn SQLITE_OK to
113f0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
11400 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
11410 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
11420 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
11430 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
11440 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
11450 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
11460 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
11470 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
11480 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
11490 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
114a0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
114b0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
114c0 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20 61 75  ror.   If the au
114d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
114e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
114f0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
11500 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
11510 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
11520 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
11530 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
11540 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
11550 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
11560 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
11570 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
11580 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
11590 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
115a0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
115b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
115c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
115d0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
115e0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
115f0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
11600 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
11610 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
11620 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
11630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11640 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
11650 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
11660 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
11670 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
11680 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
11690 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
116a0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
116b0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
116c0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
116d0 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  er code is [SQLI
116e0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
116f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
11700 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
11710 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72  ORE] then the pr
11720 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
11730 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
11740 65 64 20 74 6f 20 69 6e 73 65 72 74 20 61 20 4e  ed to insert a N
11750 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
11760 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 74 61 62  ce of.** the tab
11770 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
11780 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
11790 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
117a0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
117b0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
117c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
117d0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
117e0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
117f0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
11800 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
11810 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
11820 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20   a table..**.** 
11830 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
11840 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
11850 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
11860 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
11870 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
11880 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
11890 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
118a0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
118b0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
118c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
118d0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
118e0 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ger .** [SQLITE_
118f0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
11900 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
11910 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  es the particula
11920 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62  r action.** to b
11930 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
11940 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
11950 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  sixth.** paramet
11960 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
11970 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
11980 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
11990 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a  that contain .**
119a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
119b0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
119c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
119d0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  rized..**.** An 
119e0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
119f0 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e  ed when preparin
11a00 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
11a10 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
11a20 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f  ed.** source, to
11a30 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
11a40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
11a50 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
11a60 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61  cess data.** tha
11a70 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  t they are not a
11a80 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
11a90 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
11aa0 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65  ot try to.** exe
11ab0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
11ac0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
11ad0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
11ae0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
11af0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
11b00 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
11b10 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
11b20 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
11b30 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
11b40 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
11b50 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
11b60 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
11b70 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
11b80 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
11b90 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
11ba0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
11bb0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
11bc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
11bd0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
11be0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
11bf0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
11c00 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72   SQL is being pr
11c10 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73 61  epared that disa
11c20 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
11c30 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43  .** except SELEC
11c40 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a  T statements.  .
11c50 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
11c60 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
11c70 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
11c80 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
11c90 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
11ca0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
11cb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
11cc0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
11cd0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
11ce0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
11cf0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
11d00 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
11d10 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
11d20 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
11d30 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
11d40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
11d50 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
11d60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
11d70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
11d80 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b  nly during .** [
11d90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
11da0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
11db0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
11dc0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
11dd0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
11de0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
11df0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
11e00 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  tep()]..**.** IN
11e10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
11e20 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71  {F12501} The [sq
11e30 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
11e40 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  izer(D,...)] int
11e50 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
11e60 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
11e70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11e80 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ck with database
11e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
11ea0 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54 68  *.** {F12502} Th
11eb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
11ec0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
11ed0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
11ee0 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ts are.**       
11ef0 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65     being compile
11f00 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d  d.**.** {F12503}
11f10 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
11f20 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
11f30 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  rns any value ot
11f40 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
11f50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
11f60 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
11f70 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
11f80 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  NY] then.**     
11f90 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
11fa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
11fb0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
11fc0 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ll that caused.*
11fd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
11fe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11ff0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
12000 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20  fail with an.** 
12010 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
12020 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
12030 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  de and an approp
12040 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
12050 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  age..**.** {F125
12060 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  04} When the aut
12070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12080 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12090 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74  _OK], the operat
120a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
120b0 64 65 73 63 72 69 62 65 64 20 69 73 20 63 6f 64  described is cod
120c0 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
120d0 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 65 6e  ** {F12505} When
120e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
120f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12100 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
12110 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12120 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
12130 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
12140 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
12150 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
12160 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
12170 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
12180 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
12190 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
121a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
121b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
121c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
121d0 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
121e0 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
121f0 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
12200 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 20 74  ** {F12506} If t
12210 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
12220 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
12230 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
12240 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
12250 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
12260 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
12270 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
12280 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
12290 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
122a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
122b0 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
122c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
122d0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
122e0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
122f0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
12300 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
12310 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
12320 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
12330 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
12340 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
12350 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
12360 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 37 7d  ..**.** {F12507}
12370 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
12380 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
12390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
123a0 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
123b0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
123c0 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
123d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
123e0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
123f0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
12400 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
12410 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
12420 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
12430 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a  LITE_DENY]. .**.
12440 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65 20  ** {F12510} The 
12450 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12460 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
12470 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
12480 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
12490 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
124a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
124b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
124c0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
124d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ace..**.** {F125
124e0 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
124f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12500 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
12510 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20 20 20  nteger .**      
12520 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
12530 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
12540 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
12550 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
12560 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
12570 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
12580 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 32  d..**.** {F12512
12590 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
125a0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
125b0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
125c0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
125d0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
125e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
125f0 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20 20  t contain .**   
12600 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61         additiona
12610 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
12620 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
12630 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
12640 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68  ** {F12520} Each
12650 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
12660 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12670 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  ()] overrides th
12680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  e.**          an
12690 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
126a0 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
126b0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31  r..**.** {F12521
126c0 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
126d0 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
126e0 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
126f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
12700 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
12710 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20  .**.** {F12522} 
12720 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
12730 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
12740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
12750 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
12760 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
12770 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
12780 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
12790 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
127a0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
127b0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
127c0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
127d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
127e0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
127f0 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a  des {F12590}.**.
12800 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12810 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
12820 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12830 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
12840 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
12850 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
12860 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
12870 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
12880 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
12890 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
128a0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
128b0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
128c0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
128d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
128e0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
128f0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
12900 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
12910 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
12920 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
12930 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
12940 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
12950 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
12960 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
12970 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
12980 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
12990 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
129a0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
129b0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
129c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
129d0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
129e0 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a  odes {F12550}.**
129f0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
12a00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
12a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
12a20 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
12a30 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
12a40 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
12a50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74   authorizer cert
12a60 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
12a70 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
12a80 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
12a90 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
12aa0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
12ab0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
12ac0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
12ad0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
12ae0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
12af0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
12b00 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
12b10 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
12b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
12b30 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
12b40 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
12b50 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
12b60 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
12b70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
12b80 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   be .** authoriz
12b90 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
12ba0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
12bb0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
12bc0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
12bd0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
12be0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
12bf0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
12c00 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
12c10 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
12c20 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
12c30 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
12c40 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
12c50 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
12c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
12c70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
12c80 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
12c90 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63   "temp", .** etc
12ca0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
12cb0 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
12cc0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
12cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
12ce0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
12cf0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
12d00 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
12d10 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
12d20 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
12d30 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
12d40 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
12d50 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
12d60 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a   directly from .
12d70 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
12d80 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   code..**.** INV
12d90 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
12da0 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f  F12551} The seco
12db0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
12dc0 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  an .**          
12dd0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12de0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12df0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
12e00 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67   always an integ
12e10 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
12e20 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
12e30 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
12e40 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
12e50 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
12e60 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
12e70 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
12e80 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33 72   {F12552} The 3r
12e90 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
12ea0 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a 2a 20  ters to the .** 
12eb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
12ec0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12ed0 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e   | authorization
12ee0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
12ef0 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on].**          
12f00 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
12f10 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
12f20 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 0a 2a  ding on which .*
12f30 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
12f40 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72  TE_COPY | author
12f50 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73  izer code] is us
12f60 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
12f70 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
12f80 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20 35  * {F12553} The 5
12f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
12fa0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12fb0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12fc0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12fd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
12fe0 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
12ff0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61         of the da
13000 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a  tabase (example:
13010 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
13020 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
13030 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  able..**.** {F12
13040 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72  554} The 6th par
13050 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
13060 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13070 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
13080 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
13090 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
130a0 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
130b0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
130c0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
130d0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
130e0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20  nsible for.**   
130f0 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73         the acces
13100 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
13110 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
13120 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
13130 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 20 20  ctly from .**   
13140 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c         top-level
13150 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
13160 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13180 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
13190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
131a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
131b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
131c0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
131d0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
131e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
131f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
13200 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13210 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
13220 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
13230 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13240 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13250 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13260 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
13270 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
13280 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
13290 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
132a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
132b0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
132c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
132d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
132e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
132f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
13300 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
13310 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
13320 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
13330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13340 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
13350 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
13360 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13370 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13390 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
133a0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
133b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
133c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
133d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
133e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
133f0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
13400 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
13410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13430 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
13440 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
13450 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13460 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13480 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
13490 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
134a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
134b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
134c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
134d0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
134e0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
134f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13500 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13520 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
13530 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
13540 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
13550 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
13560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13570 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
13580 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
13590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
135a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
135b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
135c0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
135d0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
135e0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
135f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
13610 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
13620 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
13630 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
13640 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
13660 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
13670 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
13680 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
13690 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
136a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
136b0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
136c0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
136d0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
136e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
136f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
13700 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
13710 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
13720 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13730 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13740 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
13750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
13760 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
13770 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
13780 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
13790 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
137a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
137b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
137c0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
137d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
137e0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
137f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
13800 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
13810 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13830 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
13840 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
13850 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
13860 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13880 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
13890 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
138a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
138b0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
138c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
138d0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
138e0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
138f0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
13900 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13920 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
13930 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
13940 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
13950 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13970 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
13980 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
13990 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
139a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
139b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
139c0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
139d0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
139e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
139f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13a10 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
13a20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
13a30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
13a40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13a60 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
13a70 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
13a80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
13a90 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
13aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13ab0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
13ac0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
13ad0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
13ae0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
13af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
13b00 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
13b10 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74     31   /* Funct
13b20 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ion Name   NULL 
13b30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
13b50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
13b60 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
13b70 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
13b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
13b90 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
13ba0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  ng Functions {F1
13bb0 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2280}.**.** Thes
13bc0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
13bd0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
13be0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
13bf0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
13c00 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
13c10 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
13c20 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
13c30 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
13c40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
13c50 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
13c60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
13c70 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
13c80 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
13c90 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
13ca0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
13cb0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
13cc0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
13cd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
13ce0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
13cf0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
13d00 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
13d10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
13d20 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
13d30 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
13d40 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
13d50 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
13d60 69 67 67 65 72 73 75 62 70 72 6f 67 72 61 6d 20  iggersubprogram 
13d70 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
13d80 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
13d90 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
13da0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
13db0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
13dc0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
13dd0 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63  er..** .** The c
13de0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
13df0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
13e00 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
13e10 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
13e20 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
13e30 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
13e40 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
13e50 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
13e60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
13e70 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
13e80 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
13e90 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
13ea0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
13eb0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
13ec0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
13ed0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f   The sqlite3_pro
13ee0 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75  file() API is cu
13ef0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
13f00 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
13f10 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63  and.** is subjec
13f20 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
13f30 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75  emoval in a futu
13f40 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a  re release..**.*
13f50 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65  * The trigger re
13f60 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20  porting feature 
13f70 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  of the trace cal
13f80 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65  lback is conside
13f90 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  red.** experimen
13fa0 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
13fb0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
13fc0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
13fd0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46  e releases..** F
13fe0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
13ff0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  f SQLite might a
14000 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63  lso add new trac
14010 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69  e callback .** i
14020 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  nvocations..**.*
14030 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14040 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65  .** {F12281} The
14050 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14060 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
14070 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
14080 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
14090 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51    whenever an SQ
140a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  L statement firs
140b0 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63  t begins to exec
140c0 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ute and.**      
140d0 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74      whenever a t
140e0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
140f0 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  m first begins t
14100 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  o run..**.** {F1
14110 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20  2282} Each call 
14120 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
14130 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  e()] overrides t
14140 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  he previously.**
14150 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
14160 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62  ered trace callb
14170 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ack..**.** {F122
14180 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65  83} A NULL trace
14190 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c   callback disabl
141a0 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a  es tracing..**.*
141b0 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66  * {F12284} The f
141c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
141d0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
141e0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
141f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14200 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
14210 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  as the 3rd argum
14220 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
14230 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  trace()]..**.** 
14240 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65 63  {F12285} The sec
14250 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14260 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
14270 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
14280 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
14290 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 20  ted UTF8 string 
142a0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
142b0 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20  riginal text.** 
142c0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
142d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
142e0 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69   it was passed i
142f0 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nto [sqlite3_pre
14300 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
14310 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
14320 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20  uivalent, or an 
14330 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69  SQL comment indi
14340 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e  cating the begin
14350 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
14360 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75   of a trigger su
14370 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20  bprogram..**.** 
14380 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c  {F12287} The cal
14390 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
143a0 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
143b0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
143c0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
143d0 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20          as each 
143e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
143f0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nishes..**.** {F
14400 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74  12288} The first
14410 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14420 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
14430 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
14440 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
14450 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
14460 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
14470 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
14480 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
14490 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
144a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
144b0 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
144c0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
144d0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
144e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
144f0 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20  e complete text 
14500 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
14510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14520 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65   as it was proce
14530 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ssed by [sqlite3
14540 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
14550 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
14560 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
14570 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65  .** {F12290} The
14580 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14590 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
145a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
145b0 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20  estimate.**     
145c0 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62       of the numb
145d0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
145e0 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  s of wall-clock 
145f0 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f  time required to
14600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e  .**          run
14610 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14620 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f  nt from start to
14630 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64   finish..*/.void
14640 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
14650 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
14660 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
14670 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
14680 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
14690 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
146a0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
146b0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
146c0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
146d0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
146e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
146f0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
14700 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
14710 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  910}.**.** This 
14720 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
14730 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
14740 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
14750 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
14760 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
14770 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
14780 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
14790 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
147a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
147b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
147c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
147d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
147e0 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  .   An example u
147f0 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
14800 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
14810 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
14820 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
14830 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
14840 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
14850 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14860 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
14870 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ertion is.** int
14880 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
14890 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
148a0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
148b0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
148c0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64  utton on a GUI d
148d0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
148e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
148f0 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20  ** {F12911} The 
14900 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
14910 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
14920 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
14930 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20  s_handler()].** 
14940 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
14950 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
14960 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
14970 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
14980 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14990 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
149a0 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20 70  * {F12912} The p
149b0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
149c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
149d0 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
149e0 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
149f0 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
14a00 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
14a10 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14a20 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
14a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
14a40 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
14a50 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69  ] call that regi
14a60 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
14a70 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e     the callback.
14a80 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66 20    <todo>What if 
14a90 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  N is less than 1
14aa0 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
14ab0 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  F12913} The prog
14ac0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
14ad0 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
14ae0 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
14af0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
14b00 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
14b10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
14b20 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  r()]..**.** {F12
14b30 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20  914} The fourth 
14b40 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74 65  argument [sqlite
14b50 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
14b60 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20 20  er()] is a.***  
14b70 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e         void poin
14b80 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
14b90 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14ba0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
14bb0 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69  function each ti
14bc0 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  me it is invoked
14bd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d  ..**.** {F12915}
14be0 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
14bf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
14c00 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20  esults in fewer 
14c10 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
14c20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
14c30 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20 20   executed,.**   
14c40 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
14c50 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
14c60 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b  k is never invok
14c70 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a  ed. {END}.** .**
14c80 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79 20   {F12916} Every 
14c90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
14ca0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
14cb0 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  r()].**         
14cc0 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20   overwrites any 
14cd0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
14ce0 74 65 72 65 20 70 72 6f 67 72 65 73 73 20 68 61  tere progress ha
14cf0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ndler..**.** {F1
14d00 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f  2917} If the pro
14d10 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
14d20 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74  llback is NULL t
14d30 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a  hen no progress.
14d40 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
14d50 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  ler is invoked..
14d60 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49  **.** {F12918} I
14d70 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
14d80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14d90 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
14da0 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20  han 0, then.**  
14db0 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61          the beha
14dc0 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71  vior is a if [sq
14dd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14de0 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c  )] had been call
14df0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
14e00 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14e10 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
14e20 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
14e30 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
14e40 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
14e50 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
14e60 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46  se Connection {F
14e70 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12700}.**.** The
14e80 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
14e90 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
14ea0 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
14eb0 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20  ame.** is given 
14ec0 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  by the filename 
14ed0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
14ee0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
14ef0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
14f00 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66 6f  d as UTF-8.** fo
14f10 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
14f20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
14f30 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
14f40 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20 74  s UTF-16.** in t
14f50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
14f60 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
14f70 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
14f80 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  An [sqlite3*] ha
14f90 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 20  ndle is usually 
14fa0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
14fb0 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e  b, even.** if an
14fc0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
14fd0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
14fe0 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74 65 20  on is if SQLite 
14ff0 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20  is unable.** to 
15000 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
15010 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
15020 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61 20  ite3] object, a 
15030 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  NULL will.** be 
15040 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
15050 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
15060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
15070 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
15080 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
15090 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
150a0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a  nd/or created).*
150b0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  * successfully, 
150c0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  then [SQLITE_OK]
150d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
150e0 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20 65  therwise an.** e
150f0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
15100 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
15110 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
15120 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
15130 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69  rmsg16()]  routi
15140 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
15150 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
15160 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
15170 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
15180 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
15190 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
151a0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
151b0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
151c0 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  TF-8 if.** [sqli
151d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
151e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
151f0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  )] is called and
15200 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
15210 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
15220 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  der if [sqlite3_
15230 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
15240 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
15250 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
15260 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
15270 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
15280 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
15290 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ed with the [sql
152a0 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
152b0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
152c0 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a   by passing it.*
152d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  * to [sqlite3_cl
152e0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
152f0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
15300 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
15310 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15320 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
15330 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
15340 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78  3_open()] .** ex
15350 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
15360 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
15370 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
15380 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
15390 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
153a0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
153b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
153c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
153d0 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f   can be.** one o
153e0 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  f:.**.** <ol>.**
153f0 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
15400 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a  PEN_READONLY].**
15410 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
15420 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a  PEN_READWRITE].*
15430 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
15440 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
15450 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
15460 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  REATE].** </ol>.
15470 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15480 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20  value opens the 
15490 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e  database read-on
154a0 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 64  ly. .** If the d
154b0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
154c0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
154d0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
154e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
154f0 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70  second option op
15500 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ens.** the datab
15510 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
15520 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
15530 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
15540 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69  ing only if.** i
15550 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
15560 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20  ite protected.  
15570 49 6e 20 65 69 74 68 65 72 20 63 61 73 65 20 74  In either case t
15580 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d  he database.** m
15590 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
155a0 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73  t or an error is
155b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
155c0 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20  third option.** 
155d0 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
155e0 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
155f0 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63  nd writing and c
15600 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20  reates it if it 
15610 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65  does.** not alre
15620 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68  ady exist..** Th
15630 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20  e third options 
15640 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  is behavior that
15650 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
15660 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
15670 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
15680 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
15690 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
156a0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
156b0 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
156c0 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72  vate.** in-memor
156d0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
156e0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
156f0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nnection.  This 
15700 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74  in-memory.** dat
15710 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
15720 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  h when the datab
15730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
15740 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
15750 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
15760 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b  SQLite might mak
15770 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
15780 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
15790 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65  names.** that be
157a0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
157b0 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20   character.  It 
157c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
157d0 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64  hat .** when a d
157e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
157f0 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67   really does beg
15800 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74  in with.** ":" t
15810 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74  hat you prefix t
15820 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
15830 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65   a pathname like
15840 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69   "./" to.** avoi
15850 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
15860 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
15870 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
15880 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
15890 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a  ivate temporary.
158a0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
158b0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
158c0 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61  ted.  This priva
158d0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
158e0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
158f0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
15900 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
15910 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15920 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
15930 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
15940 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15950 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
15960 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
15970 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
15980 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
15990 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
159a0 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65   system .** inte
159b0 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e  rface that the n
159c0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
159d0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
159e0 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  e.  If the.** fo
159f0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15a00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15a10 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
15a20 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a  t [sqlite3_vfs].
15a30 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  ** object is use
15a40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
15a50 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72   to windows user
15a60 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
15a70 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
15a80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
15a90 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74  ent.** of [sqlit
15aa0 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
15ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15ac0 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  )] must be UTF-8
15ad0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
15ae0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
15af0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
15b00 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
15b10 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
15b20 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
15b30 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
15b40 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
15b50 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
15b60 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  hem into.** [sql
15b70 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
15b80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15b90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
15ba0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
15bb0 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2701} The [sqlit
15bc0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
15bd0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
15be0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
15bf0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15c00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63  ()] interfaces c
15c10 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20  reate a new.**  
15c20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
15c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
15c40 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
15c50 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61            the da
15c60 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65  tabase file give
15c70 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74  n in their first
15c80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
15c90 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66  * {F12702} The f
15ca0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
15cb0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
15cc0 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  as UTF-8.**     
15cd0 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65       for [sqlite
15ce0 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
15cf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15d00 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
15d10 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
15d20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
15d30 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
15d40 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
15d50 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75  ** {F12703} A su
15d60 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
15d70 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
15d80 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
15d90 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a  3_open16()], .**
15da0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
15db0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15dc0 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65   writes a pointe
15dd0 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
15de0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
15df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
15e00 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b  o *ppDb..**.** {
15e10 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c  F12704} The [sql
15e20 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
15e30 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15e40 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
15e50 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
15e60 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
15e70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15e80 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73  OK] upon success
15e90 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
15ea0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
15eb0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
15ec0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
15ed0 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61  F12706} The defa
15ee0 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
15ef0 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
15f00 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
15f10 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
15f20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
15f30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15f40 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  _v2()] will be U
15f50 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  TF-8..**.** {F12
15f60 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74  707} The default
15f70 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
15f80 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
15f90 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
15fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
15fb0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77  ite3_open16()] w
15fc0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a  ill be UTF-16..*
15fd0 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68  *.** {F12709} Th
15fe0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
15ff0 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,D)] interface 
16000 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
16010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16020 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
16030 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68  D,G,0)] where th
16040 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73  e G parameter is
16050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16060 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
16070 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45  ITE]|[SQLITE_OPE
16080 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a  N_CREATE]..**.**
16090 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68 65   {F12711} If the
160a0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
160b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
160c0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
160d0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
160e0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
160f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
16100 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61  NLY] then the da
16110 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
16120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
16130 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a   reading only..*
16140 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66  *.** {F12712} If
16150 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
16160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16170 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
16180 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
16190 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
161a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
161b0 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74  EADWRITE] then t
161c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
161d0 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
161e0 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72    reading and wr
161f0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
16200 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e  e, or for readin
16210 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a  g only if the.**
16220 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69            file i
16230 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
16240 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
16250 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  ng system..**.**
16260 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68 65   {F12713} If the
16270 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
16280 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
16290 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73  (F,D,G,V)] omits
162a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
162b0 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
162c0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
162d0 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
162e0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
162f0 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79        previously
16300 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
16310 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
16320 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20  .** {F12714} If 
16330 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
16340 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16350 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  (v2(F,D,G,V)] co
16360 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
16370 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
16380 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
16390 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
163a0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
163b0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
163c0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68  iously exist, th
163d0 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  en an attempt is
163e0 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20   made to create 
163f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
16400 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64  initialize the d
16410 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  atabase..**.** {
16420 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66  F12717} If the f
16430 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
16440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16450 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16460 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
16470 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
16480 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
16490 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
164a0 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20   an private,.** 
164b0 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
164c0 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  al, in-memory da
164d0 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65  tabase is create
164e0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
164f0 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20  tion..**        
16500 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
16510 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
16520 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
16530 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
16540 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
16550 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
16560 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
16570 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65  719} If the file
16580 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20  name is NULL or 
16590 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
165a0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
165b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
165c0 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  ermeral on-disk 
165d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
165e0 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
165f0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
16600 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16610 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
16620 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
16630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
16640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16650 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
16660 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {F12721} The [da
16670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16680 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a  n] created by .*
16690 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
166a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
166b0 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74  G,V)] will use t
166c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
166d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
166e0 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
166f0 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
16700 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  r, or.**        
16710 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73    the default [s
16720 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
16730 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c  ct is V is a NUL
16740 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e  L pointer..*/.in
16750 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
16760 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
16770 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
16780 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
16790 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
167a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
167b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
167c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
167d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
167e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
167f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
16800 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
16810 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
16820 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
16830 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
16840 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
16850 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
16860 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
16870 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
16880 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
16890 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
168a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
168b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
168c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
168d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
168e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
168f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
16900 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
16910 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
16920 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
16930 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
16940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16950 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
16960 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31  And Messages {F1
16970 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2800}.**.** The 
16980 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16990 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
169a0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
169b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
169c0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
169d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
169e0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
169f0 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f  sult code].** fo
16a00 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
16a10 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
16a20 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
16a30 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b  ciated.** with [
16a40 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20  sqlite3] handle 
16a50 27 64 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72  'db'. If a prior
16a60 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
16a70 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74   but the.** most
16a80 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
16a90 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
16aa0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
16ab0 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
16ac0 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  e().** is undefi
16ad0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
16ae0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
16af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
16b00 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
16b10 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
16b20 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
16b30 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
16b40 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
16b50 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
16b60 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
16b70 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
16b80 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
16b90 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
16ba0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
16bb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
16bc0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
16bd0 72 79 20 77 69 74 68 20 66 72 65 65 69 6e 67 20  ry with freeing 
16be0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
16bf0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
16c00 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
16c10 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
16c20 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
16c30 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
16c40 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
16c50 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
16c60 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
16c70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16c80 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {F12801} The [s
16c90 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
16ca0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
16cb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
16cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16cd0 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
16ce0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20   code] or.**    
16cf0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f        [SQLITE_IO
16d00 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
16d10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
16d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
16d30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
16d40 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
16d50 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
16d60 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
16d70 77 69 74 68 20 5b 64 61 74 61 62 61 73 65 20 63  with [database c
16d80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
16d90 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65  .** {F12803} The
16da0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16db0 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (D)] and [sqlite
16dc0 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a  3_errmsg16(D)].*
16dd0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
16de0 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67  faces return Eng
16df0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
16e00 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
16e10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
16e20 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
16e30 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
16e40 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
16e50 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  call,.**        
16e60 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74    encoded as eit
16e70 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31  her UTF8 or UTF1
16e80 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
16e90 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54  **.** {F12807} T
16ea0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
16eb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
16ec0 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
16ed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
16ee0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
16ef0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
16f00 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
16f10 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
16f20 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61  *.** {F12808} Ca
16f30 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
16f40 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
16f50 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
16f60 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
16f70 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
16f80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
16f90 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
16fa0 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
16fb0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
16fc0 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
16fd0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
16fe0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16ff0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
17000 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
17010 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
17020 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20  .**.** {F12809} 
17030 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20  Interfaces that 
17040 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74  are not associat
17050 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66  ed with a specif
17060 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
17070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17080 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a  ion] (examples:.
17090 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
170a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
170b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  or [sqlite3_enab
170c0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
170d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  )].**          d
170e0 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  o not change the
170f0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
17100 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
17110 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
17120 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
17130 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  rmsg()], or [sql
17140 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
17150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17160 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
17170 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
17180 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
17190 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
171a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
171b0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
171c0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
171d0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
171e0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30  ent Object {F130
171f0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
17200 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
17210 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
17220 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
17230 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
17240 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
17250 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51  resent single SQ
17260 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54  L statements.  T
17270 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  his.** object is
17280 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
17290 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
172a0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20  statement" or a 
172b0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
172c0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
172d0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
172e0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20  tement"..** .** 
172f0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
17300 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
17310 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
17320 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
17330 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
17340 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
17350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
17360 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
17370 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
17380 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
17390 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
173a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
173b0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b   using.**      [
173c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
173d0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
173e0 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a  _* interfaces]..
173f0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
17400 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
17410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
17420 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
17430 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
17440 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
17450 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
17460 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
17470 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
17480 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
17490 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
174a0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
174b0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
174c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
174d0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
174e0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
174f0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
17500 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
17510 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
17520 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
17530 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
17540 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
17550 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
17560 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
17570 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
17580 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36  me Limits {F1276
17590 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
175a0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
175b0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
175c0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
175d0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
175e0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
175f0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
17600 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
17610 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
17620 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17630 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
17640 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
17650 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
17660 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
17670 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
17680 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
17690 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
176a0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
176b0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
176c0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
176d0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
176e0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
176f0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
17700 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
17710 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
17720 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
17730 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
17740 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
17750 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
17760 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
17770 68 61 6e 67 65 64 2e 0a 2a 2a 20 49 66 20 74 68  hanged..** If th
17780 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 7a  e new limit is z
17790 65 72 6f 2c 20 74 68 65 20 63 6f 6e 73 74 72 75  ero, the constru
177a0 63 74 20 62 65 63 6f 6d 65 73 20 75 6e 6c 69 6d  ct becomes unlim
177b0 69 74 65 64 2e 20 20 41 63 74 75 61 6c 6c 79 2c  ited.  Actually,
177c0 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 68  .** there is a h
177d0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
177e0 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  on the size of a
177f0 6c 6c 20 63 6f 6e 73 74 72 75 63 74 73 20 74 68  ll constructs th
17800 61 74 0a 2a 2a 20 69 73 20 64 65 74 65 72 6d 69  at.** is determi
17810 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ned at compile-t
17820 69 6d 65 2e 20 20 46 6f 72 20 74 68 65 20 6c 69  ime.  For the li
17830 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20  mit category of 
17840 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  .** SQLITE_LIMIT
17850 5f 58 59 5a 20 74 68 65 20 68 61 72 64 20 75 70  _XYZ the hard up
17860 70 65 72 20 62 6f 75 6e 64 20 69 73 20 74 68 65  per bound is the
17870 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
17880 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
17890 5f 4d 41 58 5f 58 59 5a 2e 20 20 41 74 74 65 6d  _MAX_XYZ.  Attem
178a0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
178b0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
178c0 73 0a 2a 2a 20 68 61 72 64 20 75 70 70 65 72 20  s.** hard upper 
178d0 62 6f 75 6e 64 20 61 72 65 20 73 69 6c 65 6e 74  bound are silent
178e0 6c 79 20 74 72 75 6e 63 61 74 65 64 2e 0a 2a 2a  ly truncated..**
178f0 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
17900 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
17910 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
17920 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
17930 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
17940 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
17950 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
17960 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
17970 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
17980 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
17990 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
179a0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
179b0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
179c0 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73  be a.** webbrows
179d0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
179e0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
179f0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
17a00 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
17a10 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
17a20 72 6f 6c 6c 65 64 20 62 79 20 6a 61 76 61 73 63  rolled by javasc
17a30 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
17a40 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
17a50 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 65 74 2e  of the internet.
17a60 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
17a70 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
17a80 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
17a90 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
17aa0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
17ab0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
17ac0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
17ad0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
17ae0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
17af0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
17b00 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
17b10 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 68  ervice.** attach
17b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
17b30 65 72 66 61 63 65 20 69 73 20 63 75 72 72 65 6e  erface is curren
17b40 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65  tly considered e
17b50 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
17b60 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f  is subject.** to
17b70 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
17b80 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69 6f 72  al without prior
17b90 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49   notice..**.** I
17ba0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
17bb0 20 7b 46 31 32 37 36 33 7d 20 41 20 73 75 63 63   {F12763} A succ
17bc0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
17bd0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
17be0 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73  C,V)] where V is
17bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73  .**          pos
17c00 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 68  itive changes th
17c10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69  e.**          li
17c20 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  mit on the size 
17c30 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69  of construct C i
17c40 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
17c50 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
17c60 20 20 20 20 20 20 74 6f 20 74 68 65 20 6c 65 73        to the les
17c70 73 6f 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65  sor of V and the
17c80 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
17c90 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a  d on the size.**
17ca0 20 20 20 20 20 20 20 20 20 20 6f 66 20 43 20 74            of C t
17cb0 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f  hat is set at co
17cc0 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile-time..**.*
17cd0 2a 20 7b 46 31 32 37 36 33 7d 20 41 20 73 75 63  * {F12763} A suc
17ce0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
17cf0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
17d00 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
17d10 73 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20  s zero.**       
17d20 20 20 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c     changes the l
17d30 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
17d40 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
17d50 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  in.**          [
17d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17d70 69 6f 6e 5d 20 44 20 74 6f 20 62 65 20 74 68 65  ion] D to be the
17d80 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
17d90 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a  d on the size.**
17da0 20 20 20 20 20 20 20 20 20 20 6f 66 20 43 20 74            of C t
17db0 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f  hat is set at co
17dc0 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile-time..**.*
17dd0 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73 75 63  * {F12766} A suc
17de0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
17df0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
17e00 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
17e10 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
17e20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68         leaves th
17e30 65 20 73 74 61 74 65 20 6f 66 20 5b 64 61 74 61  e state of [data
17e40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17e50 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a   D unchanged..**
17e60 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41 20 73  .** {F12769} A s
17e70 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
17e80 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
17e90 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73  (D,C,V)] returns
17ea0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17eb0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
17ec0 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  mit on the size 
17ed0 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69  of construct C i
17ee0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
17ef0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17f00 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
17f10 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
17f20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
17f30 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
17f40 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
17f50 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
17f60 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
17f70 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
17f80 72 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a  ries {F12790}.**
17f90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
17fa0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d  t category} {lim
17fb0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
17fc0 2a 20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  * .** These cons
17fd0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
17fe0 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20  ious aspects of 
17ff0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
18000 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
18010 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69  can be limited i
18020 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20  n size by calls 
18030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
18040 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61  t()]..** The mea
18050 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
18060 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20  ious limits are 
18070 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
18080 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
18090 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
180a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
180b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
180c0 66 20 61 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20  f any.** string 
180d0 6f 72 20 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65  or blob or table
180e0 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
180f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18100 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
18110 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18120 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
18130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
18140 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18150 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
18160 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
18170 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18180 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
18190 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
181a0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
181b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
181c0 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61  SELECT or the ma
181d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
181e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
181f0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
18200 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
18210 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
18220 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18230 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
18240 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
18250 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
18260 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
18270 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
18280 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
18290 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
182a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
182b0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
182c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
182d0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
182e0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
182f0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
18300 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18310 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
18320 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18330 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18340 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
18350 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
18360 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
18370 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
18380 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
18390 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
183a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
183b0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
183c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
183d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
183e0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
183f0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
18400 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18410 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
18420 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18430 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74  um number of att
18440 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e  ached databases.
18450 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 50 41 47  SQLITE_LIMIT_PAG
18470 45 5f 43 4f 55 4e 54 3c 2f 64 74 3e 0a 2a 2a 20  E_COUNT</dt>.** 
18480 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18490 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
184a0 69 6e 20 61 20 64 61 74 61 62 61 73 65 2e 3c 2f  in a database.</
184b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
184c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
184d0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
184e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
184f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
18500 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
18510 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b  ument to the LIK
18520 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65  E or.** GLOB ope
18530 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  rators.</dd>.**.
18540 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
18550 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
18560 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
18570 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18580 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
18590 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
185a0 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
185b0 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a  be bound.</dd>.*
185c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
185d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
185e0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
185f0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
18600 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18610 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
18620 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
18630 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
18640 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
18650 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
18660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18670 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
18680 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
18690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
186a0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
186b0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
186c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
186d0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
186e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
186f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18700 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
18710 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
18720 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
18730 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
18740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18750 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
18760 45 5f 4c 49 4d 49 54 5f 50 41 47 45 5f 43 4f 55  E_LIMIT_PAGE_COU
18770 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
18780 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
18790 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
187a0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
187b0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
187c0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
187d0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
187e0 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
187f0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
18800 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
18810 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a  t {F13010}.**.**
18820 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
18830 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
18840 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
18850 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
18860 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
18870 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
18880 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a  se routines. .**
18890 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
188a0 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61  gument "db" is a
188b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
188c0 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61  ection] .** obta
188d0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
188e0 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
188f0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
18900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a  ite3_open_v2()].
18910 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
18920 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68  pen16()]. .** Th
18930 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18940 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20  t "zSql" is the 
18950 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
18960 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
18970 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
18980 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
18990 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
189a0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
189b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
189c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
189d0 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c  es UTF-8 and sql
189e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
189f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
18a00 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
18a10 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d  se UTF-16. {END}
18a20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
18a30 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
18a40 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72  less.** than zer
18a50 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
18a60 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
18a70 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
18a80 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74  ator..** If nByt
18a90 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
18aa0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
18ab0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18ac0 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65   of .** bytes re
18ad0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
18ae0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
18af0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
18b00 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
18b10 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
18b20 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
18b30 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
18b40 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c  ter or .** until
18b50 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
18b60 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
18b70 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 7d  mes first. {END}
18b80 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69  .**.** *pzTail i
18b90 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
18ba0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
18bb0 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
18bc0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53  f the.** first S
18bd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
18be0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
18bf0 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69  tines only compi
18c00 6c 65 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  les the first.**
18c10 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
18c20 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
18c30 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
18c40 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
18c50 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
18c60 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
18c70 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
18c80 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
18c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18ca0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
18cb0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
18cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
18cd0 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 73    Or if there is
18ce0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
18cf0 6d 74 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20  mt is.** set to 
18d00 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
18d10 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
18d20 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
18d30 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64   input.** is and
18d40 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
18d50 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
18d60 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
18d70 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33  to NULL..** {U13
18d80 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
18d90 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
18da0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
18db0 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  leting the.** co
18dc0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
18dd0 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ment.** using [s
18de0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
18df0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
18e00 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
18e10 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
18e20 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
18e30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
18e40 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b  herwise an .** [
18e50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
18e60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
18e70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
18e80 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
18e90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
18ea0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
18eb0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
18ec0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
18ed0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
18ee0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
18ef0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
18f00 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
18f10 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
18f20 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
18f30 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
18f40 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
18f50 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
18f60 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
18f70 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
18f80 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
18f90 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
18fa0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
18fb0 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c  the .** original
18fc0 20 53 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d   SQL text. {END}
18fd0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
18fe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18ff0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
19000 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
19010 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
19020 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
19030 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
19040 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
19050 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
19060 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
19070 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
19080 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
19090 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
190a0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
190b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
190c0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
190d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
190e0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
190f0 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
19100 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
19110 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
19120 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
19130 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
19140 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
19150 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
19160 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
19170 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
19180 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
19190 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
191a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  .** [SQLITE_SCHE
191b0 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74  MA] is now a fat
191c0 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69  al error.  Calli
191d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
191e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
191f0 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
19200 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
19210 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
19220 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
19230 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
19240 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
19250 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
19260 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
19270 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
19280 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a   return. {END}.*
19290 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
192a0 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
192b0 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20  ror occurs, .** 
192c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
192d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
192e0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
192f0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
19300 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
19310 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a  error codes]. .*
19320 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68  * The legacy beh
19330 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b  avior was that [
19340 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19350 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
19360 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b  n a generic.** [
19370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
19380 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f  sult code and yo
19390 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
193a0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
193b0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
193c0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
193d0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
193e0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
193f0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
19400 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
19410 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 72 66  " prepare interf
19420 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
19430 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
19440 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20  the error is.** 
19450 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
19460 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
19470 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
19480 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
19490 7b 46 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {F13011} The [sq
194a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
194b0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
194c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
194d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
194e0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
194f0 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
19500 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
19510 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
19520 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
19530 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
19540 7b 46 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {F13012} The [sq
19550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
19560 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
19570 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
19580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
19590 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
195a0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
195b0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
195c0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
195d0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
195e0 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
195f0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19600 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
19610 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
19620 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
19630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19640 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
19650 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
19660 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
19670 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
19680 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c  n zero, then SQL
19690 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20   text is.**     
196a0 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a       read from z
196b0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
196c0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
196d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
196e0 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20 74  ** {F13014} If t
196f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
19700 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
19710 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
19720 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
19730 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
19740 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
19750 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
19760 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
19770 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78           SQL tex
19780 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  t is read from z
19790 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  Sql..**.** {F130
197a0 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f  15} In [sqlite3_
197b0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
197c0 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20  ql,N,P,pzTail)] 
197d0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
197e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
197f0 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74  the zSql input t
19800 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72  ext contains mor
19810 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73  e than one SQL s
19820 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
19830 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20       and pzTail 
19840 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
19850 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
19860 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
19870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
19880 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
19890 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
198a0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
198b0 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20   in zSql..**    
198c0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74        <todo>What
198d0 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f   does *pzTail po
198e0 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20  int to if there 
198f0 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74  is one statement
19900 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
19910 46 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73  F13016} A succes
19920 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
19930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19940 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d  (db,zSql,N,ppStm
19950 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  t,...)].**      
19960 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74      or one of it
19970 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65  s variants write
19980 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61  s into *ppStmt a
19990 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
199a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  w.**          [p
199b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
199c0 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  t] or a pointer 
199d0 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  to NULL.**      
199e0 20 20 20 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74      if zSql cont
199f0 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
19a00 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
19a10 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 20  ce or comments. 
19a20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20  .**.** {F13019} 
19a30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
19a40 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  pare_v2()] inter
19a50 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72  face and its var
19a60 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20  iants return.** 
19a70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19a80 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f  _OK] or an appro
19a90 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
19aa0 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65  de] upon failure
19ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31 7d  ..**.** {F13021}
19ac0 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   Before [sqlite3
19ad0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
19ae0 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a  ,nByte,ppStmt,pz
19af0 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a  Tail)] or its.**
19b00 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e            varian
19b10 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  ts returns an er
19b20 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f  ror (any value o
19b30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
19b40 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20 20 20 20  E_OK]).**       
19b50 20 20 20 69 74 20 66 69 72 73 74 20 73 65 74 73     it first sets
19b60 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c   *ppStmt to NULL
19b70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19b80 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
19b90 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
19ba0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
19bb0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
19bc0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
19bd0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
19be0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
19bf0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
19c00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
19c10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
19c20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
19c30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
19c40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
19c50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
19c60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
19c70 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
19c80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
19c90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
19ca0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
19cb0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
19cc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
19cd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
19ce0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
19cf0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
19d00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
19d10 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
19d20 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
19d30 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
19d40 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
19d50 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
19d60 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
19d70 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
19d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
19d90 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
19da0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
19db0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
19dc0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
19dd0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
19de0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
19df0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
19e00 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
19e10 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  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 76 6f 69  e */.  const voi
19e50 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *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 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
19e80 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
19e90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
19ea0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
19eb0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
19ec0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
19ed0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
19ee0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
19ef0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
19f00 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
19f10 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
19f20 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
19f30 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
19f40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
19f50 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
19f60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
19f70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
19f80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
19f90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
19fa0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
19fb0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
19fc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
19fd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
19fe0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
19ff0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1a000 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1a010 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1a020 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1a030 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1a040 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a050 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1a060 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1a070 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1a080 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1a090 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74  .** CAPIREF: Ret
1a0a0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1a0b0 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a 2a  t SQL {F13100}.*
1a0c0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 65  *.** This intere
1a0d0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1a0e0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1a0f0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1a100 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1a110 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1a120 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1a130 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a   statement]..**.
1a140 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1a150 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49 66  *.** {F13101} If
1a160 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1a170 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1a180 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   as .**         
1a190 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74   the an argument
1a1a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   to [sqlite3_sql
1a1b0 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
1a1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d  .**          com
1a1d0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1a1e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1a1f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
1a200 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a210 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1a220 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
1a230 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1a240 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
1a250 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a260 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  o a.**          
1a270 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a280 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1a290 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  g a UTF-8 render
1a2a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1a2b0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  of the original 
1a2c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1a2d0 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49 66  *.** {F13102} If
1a2e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1a2f0 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1a300 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   as .**         
1a310 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74   the an argument
1a320 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   to [sqlite3_sql
1a330 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
1a340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d  .**          com
1a350 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1a360 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1a370 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
1a380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1a390 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
1a3a0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
1a3b0 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75  qlite3_sql()] fu
1a3c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1a3d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1a3e0 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54 68  *.** {F13103} Th
1a3f0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
1a400 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71  d by [sqlite3_sq
1a410 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75  l(S)] is valid u
1a420 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20  ntil the.**     
1a430 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1a440 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64  tatement] S is d
1a450 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71  eleted using [sq
1a460 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
1a470 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1a480 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1a490 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1a4a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1a4b0 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c  3REF:  Dynamical
1a4c0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1a4d0 62 6a 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a  bject  {F15000}.
1a4e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1a4f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1a500 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1a510 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1a520 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1a530 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1a540 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1a550 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1a560 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1a570 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1a580 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1a590 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1a5a0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66  dynamic typing f
1a5b0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1a5c0 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20 56 61   stores.  .** Va
1a5d0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1a5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1a5f0 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a 20 62  ects can be.** b
1a600 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1a610 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1a620 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1a630 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1a640 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1a650 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1a660 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1a670 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1a680 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1a690 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1a6a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1a6b0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1a6c0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1a6d0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1a6e0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1a6f0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1a700 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1a710 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1a720 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1a730 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1a740 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1a750 65 73 20 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  es .** whether o
1a760 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1a770 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1a780 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1a790 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1a7a0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1a7b0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1a7c0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1a7d0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1a7e0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1a7f0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1a800 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1a810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1a820 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1a830 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1a840 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1a850 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1a860 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1a870 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1a880 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1a890 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1a8a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1a8b0 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b 73 71  E=0 and with [sq
1a8c0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1a8d0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1a8e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1a8f0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1a900 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70 72 6f 74   between.** prot
1a910 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1a920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1a930 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1a940 74 68 65 79 20 63 61 6e 20 62 65 0a 2a 2a 20 75  they can be.** u
1a950 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 61 62  sed interchangab
1a960 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 66 6f  le.  However, fo
1a970 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
1a980 6f 72 74 61 62 69 6c 69 74 79 20 69 74 0a 2a 2a  ortability it.**
1a990 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1a9a0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1a9b0 73 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  s make the disti
1a9c0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  nction between.*
1a9d0 2a 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  * between protec
1a9e0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1a9f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1aa00 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 69  e objects even i
1aa10 66 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 73 69  f.** they are si
1aa20 6e 67 6c 65 20 74 68 72 65 61 64 65 64 2e 0a 2a  ngle threaded..*
1aa30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1aa40 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1aa50 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1aa60 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1aa70 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1aa80 6e 74 61 74 69 6f 6e 20 6f 66 20 61 70 70 6c 69  ntation of appli
1aa90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1aaa0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
1aab0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54   protected..** T
1aac0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1aad0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
1aae0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1aaf0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
1ab00 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
1ab10 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
1ab20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ab30 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
1ab40 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
1ab50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
1ab60 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
1ab70 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
1ab80 5d 2e 20 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a  ].  All other.**
1ab90 20 69 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   interfaces that
1aba0 20 75 73 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   use sqlite3_val
1abb0 75 65 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  ue require prote
1abc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1abd0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1abe0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1abf0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1ac00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ac10 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  :  SQL Function 
1ac20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b  Context Object {
1ac30 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16001}.**.** Th
1ac40 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1ac50 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1ac60 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1ac70 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1ac80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1ac90 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
1aca0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1acb0 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a 65 63  context.** objec
1acc0 74 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  t is always firs
1acd0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  t parameter to a
1ace0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1acf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ad00 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1ad10 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
1ad20 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
1ad30 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
1ad40 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56  3REF:  Binding V
1ad50 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1ad60 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 46 31  d Statements {F1
1ad70 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  3500}.**.** In t
1ad80 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69  he SQL strings i
1ad90 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1ada0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1adb0 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e  nd its.** varian
1adc0 74 73 2c 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  ts, literals may
1add0 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20 61   be replace by a
1ade0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
1adf0 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 66 6f  e.** of these fo
1ae00 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rms:.**.** <ul>.
1ae10 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1ae20 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1ae30 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1ae40 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1ae50 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1ae60 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * In the paramet
1ae70 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61  er forms shown a
1ae80 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  bove NNN is an i
1ae90 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
1aea0 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d 6e 75 6d  ** VVV alpha-num
1aeb0 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
1aec0 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ame..** The valu
1aed0 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  es of these para
1aee0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1aef0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1af00 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a 20 6f 72  ter names".** or
1af10 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
1af20 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
1af30 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1af40 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1af50 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
1af60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
1af70 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1af80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1af90 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c 77  *() routines alw
1afa0 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ays.** is a poin
1afb0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1afc0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1afd0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
1afe0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1aff0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
1b000 76 61 72 69 61 6e 74 73 2e 20 54 68 65 20 73 65  variants. The se
1b010 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
1b020 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
1b030 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1b040 6f 20 62 65 20 73 65 74 2e 20 54 68 65 0a 2a 2a  o be set. The.**
1b050 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b060 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1b070 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61   1.  When the sa
1b080 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61  me named.** para
1b090 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1b0a0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1b0b0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1b0c0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1b0d0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1b0e0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1b0f0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 20  rst occurrence. 
1b100 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f  .** The index fo
1b110 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1b120 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1b130 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1b140 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1b150 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1b160 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
1b170 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66    The index.** f
1b180 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1b190 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1b1a0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65  e of NNN..** The
1b1b0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1b1c0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1b1d0 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
1b1e0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 53  e.** parameter S
1b1f0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
1b200 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61 75  LE_NUMBER (defau
1b210 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
1b220 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
1b230 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1b240 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1b250 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1b260 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a  **.** In those.*
1b270 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1b280 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
1b290 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
1b2a0 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
1b2b0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74  of bytes.** in t
1b2c0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
1b2d0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
1b2e0 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1b2f0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
1b300 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20 76 61  /u>.** in the va
1b310 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
1b320 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1b330 73 2e 20 20 20 54 68 65 20 6e 75 6d 62 65 72 0a  s.   The number.
1b340 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73  ** of bytes does
1b350 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
1b360 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
1b370 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73   at the end of s
1b380 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68  trings..** If th
1b390 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b3a0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1b3b0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1b3c0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
1b3d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1b3e0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1b3f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1b400 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
1b410 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1b420 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1b430 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1b440 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1b450 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1b460 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1b470 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1b480 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1b490 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1b4a0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1b4b0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
1b4c0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b4d0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1b4e0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1b4f0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1b500 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1b510 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1b520 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1b530 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1b540 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1b550 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1b560 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
1b570 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1b580 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1b590 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1b5a0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1b5b0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1b5c0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1b5d0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1b5e0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1b5f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1b600 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1b610 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
1b620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1b630 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1b640 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1b650 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1b660 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1b670 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  eros.  A zeroblo
1b680 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1b690 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1b6a0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1b6b0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73  ger to hold it s
1b6c0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1b6d0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1b6e0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1b6f0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1b700 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f  erve as place-ho
1b710 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1b720 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1b730 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1b740 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1b750 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1b760 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1b770 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1b780 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1b790 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1b7a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1b7b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1b7c0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1b7d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1b7e0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1b7f0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1b800 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b810 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1b820 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1b830 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1b840 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1b850 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1b860 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1b870 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1b880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1b890 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1b8a0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1b8b0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1b8c0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1b8d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b8e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1b8f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1b900 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1b910 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1b920 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1b930 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1b940 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1b950 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1b960 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1b970 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1b980 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1b990 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
1b9a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1b9b0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1b9c0 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1b9d0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1b9e0 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1b9f0 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1ba00 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1ba10 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1ba20 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1ba30 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1ba40 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1ba50 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1ba60 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1ba70 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1ba80 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1ba90 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1baa0 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1bab0 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1bac0 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1bad0 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1bae0 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1baf0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1bb00 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1bb10 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1bb20 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1bb30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1bb50 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1bb60 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1bb70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1bb80 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1bb90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bba0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1bbb0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1bbc0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36  S:.**.** {F13506
1bbd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1bbe0 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61  repare | SQL sta
1bbf0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
1bc00 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20   recognizes.**  
1bc10 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f          tokens o
1bc20 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c  f the forms "?",
1bc30 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
1bc40 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
1bc50 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VV".**          
1bc60 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
1bc70 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20  s, where NNN is 
1bc80 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1bc90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
1bca0 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61          digits a
1bcb0 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
1bcc0 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1bcd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
1bce0 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75           alphanu
1bcf0 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73  meric characters
1bd00 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
1bd10 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a  lly followed by.
1bd20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74  **          a st
1bd30 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1bd40 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
1bd50 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
1bd60 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
1bd70 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69  * {F13509} The i
1bd80 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
1bd90 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1bda0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1bdb0 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {F13512} The ind
1bdc0 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
1bdd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1bde0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1bdf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
1be00 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
1be10 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1be20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
1be30 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1be40 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
1be50 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1be60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ter..**.** {F135
1be70 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
1be80 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
1be90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1bea0 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
1beb0 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20  ** {F13518} The 
1bec0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
1bed0 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
1bee0 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
1bef0 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
1bf00 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
1bf10 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
1bf20 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20  most occurances 
1bf30 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1bf40 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1bf50 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1bf60 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1bf70 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1bf80 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1bf90 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1bfa0 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1bfb0 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63   first occurranc
1bfc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1bfd0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1bfe0 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1bff0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1c000 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1c010 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1c020 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1c030 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1c040 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1c050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1c060 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1c070 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1c080 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1c090 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1c0a0 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1c0b0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1c0c0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1c0d0 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1c0e0 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1c0f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c100 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c110 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1c120 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1c130 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1c140 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1c150 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1c160 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1c170 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1c180 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1c190 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1c1a0 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1c1b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c1c0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c1d0 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1c1e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c1f0 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1c200 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1c210 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1c220 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1c230 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1c240 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1c250 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c260 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1c270 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1c280 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1c290 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c2a0 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1c2b0 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1c2c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c2d0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1c2e0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1c2f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1c300 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1c310 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1c320 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c330 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c340 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c350 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1c360 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1c370 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1c380 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1c390 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1c3a0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1c3b0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1c3c0 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1c3d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c3e0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1c3f0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1c400 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c410 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1c420 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1c430 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1c440 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1c450 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1c460 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1c470 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1c480 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1c490 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1c4a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1c4b0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1c4c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c4d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1c4e0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1c4f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c500 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1c510 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1c520 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1c530 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1c540 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1c550 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1c560 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1c570 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1c580 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1c590 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1c5a0 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1c5b0 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1c5c0 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1c5d0 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1c5e0 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1c5f0 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1c600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c610 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1c620 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1c630 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1c640 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1c650 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1c660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c670 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1c680 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1c690 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1c6a0 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1c6b0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1c6c0 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1c6d0 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1c6e0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1c6f0 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1c700 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1c710 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1c720 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1c730 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1c740 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1c750 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c760 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1c770 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1c780 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c790 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1c7a0 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1c7b0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1c7c0 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1c7d0 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1c7e0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1c7f0 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1c800 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1c810 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1c820 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1c830 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1c840 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1c850 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c860 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1c870 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1c880 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1c890 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1c8a0 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1c8b0 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1c8c0 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1c8d0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
1c8e0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1c8f0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
1c900 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
1c910 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
1c920 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
1c930 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
1c940 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1c950 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
1c960 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
1c970 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1c980 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
1c990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1c9a0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1c9b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1c9c0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1c9d0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1c9e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1c9f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1ca00 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1ca10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ca20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1ca30 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1ca40 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ca50 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1ca60 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1ca70 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1ca80 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1ca90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1caa0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1cab0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1cac0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1cad0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1cae0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1caf0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1cb00 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1cb10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1cb20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1cb30 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cb40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cb50 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1cb60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cb70 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1cb80 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1cb90 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1cba0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cbb0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1cbc0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1cbd0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1cbe0 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1cbf0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1cc00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1cc10 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1cc20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1cc30 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1cc40 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1cc50 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1cc60 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1cc70 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1cc80 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1cc90 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1cca0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1ccb0 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1ccc0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1ccd0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1cce0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1ccf0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1cd00 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1cd10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
1cd20 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1cd30 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1cd40 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1cd50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46   parameter..** F
1cd60 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1cd70 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1cd80 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1cd90 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  o the number of.
1cda0 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  ** unique parame
1cdb0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1cdc0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1cdd0 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65   are used, there
1cde0 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20   may.** be gaps 
1cdf0 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1ce00 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1ce10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ce20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1ce30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ce40 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1ce50 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1ce60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ce70 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1ce80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1ce90 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54  **.** {F13601} T
1cea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1ceb0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1cec0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
1ced0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1cee0 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
1cef0 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
1cf00 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
1cf10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1cf20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1cf30 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a  t] S, or 0 if S.
1cf40 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
1cf50 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
1cf60 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
1cf70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1cf80 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1cf90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1cfa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1cfb0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1cfc0 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
1cfd0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1cfe0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1cff0 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1d000 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53  of the n-th.** S
1d010 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1d020 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1d030 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1d040 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1d050 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
1d060 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1d070 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
1d080 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
1d090 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
1d0a0 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
1d0b0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1d0c0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1d0d0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1d0e0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
1d0f0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
1d100 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
1d110 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1d120 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61  "?" or "?NNN" ha
1d130 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  ve no name..**.*
1d140 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1d150 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1d160 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1d170 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1d180 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1d190 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1d1a0 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1d1b0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1d1c0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1d1d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1d1e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1d1f0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74  s.** always in t
1d200 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1d210 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
1d220 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
1d230 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
1d240 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
1d250 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
1d260 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
1d270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d280 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1d290 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d2b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d2c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d2d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1d2e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1d2f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d300 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1d310 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1d320 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20  .**.** {F13621} 
1d330 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
1d340 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d350 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1d360 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1d370 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e       a UTF-8 ren
1d380 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61  dering of the na
1d390 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  me of the SQL pa
1d3a0 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20  rameter in.**   
1d3b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1d3c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
1d3d0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
1d3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
1d3f0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
1d400 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
1d410 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
1d420 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1d430 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
1d440 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
1d450 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1d460 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20 20 20 20  er "?" or.**    
1d470 20 20 20 20 20 20 61 20 6e 75 6d 62 65 72 65 64        a numbered
1d480 20 70 61 72 61 6d 65 74 65 72 20 22 3f 4e 4e 4e   parameter "?NNN
1d490 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
1d4a0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1d4b0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1d4c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d4d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d4e0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1d4f0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1d500 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36  Given Name {F136
1d510 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  40}.**.** Return
1d520 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1d530 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1d540 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1d550 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1d560 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1d570 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1d580 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1d590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1d5a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d5b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1d5c0 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
1d5d0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1d5e0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1d5f0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
1d600 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
1d610 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
1d620 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
1d630 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
1d640 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
1d650 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
1d660 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
1d670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d680 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1d690 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1d6a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1d6b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1d6c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d6d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1d6e0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1d6f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d700 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1d710 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1d720 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65  .** {F13641} The
1d730 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d740 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
1d750 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1d760 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d770 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
1d780 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
1d790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d7a0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
1d7b0 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
1d7c0 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
1d7d0 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
1d7e0 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
1d7f0 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
1d800 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d810 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d820 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1d830 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1d840 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1d850 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1d860 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1d870 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1d880 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
1d890 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
1d8a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
1d8b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
1d8c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
1d8d0 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
1d8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d8f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
1d900 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
1d910 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
1d920 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1d930 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
1d940 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
1d950 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
1d960 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1d970 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {F13661} The [sq
1d980 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1d990 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
1d9a0 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a  ce resets all.**
1d9b0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61            SQL pa
1d9c0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
1d9d0 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1d9e0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
1d9f0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e         back to N
1da00 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1da10 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1da20 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
1da30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1da40 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
1da50 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
1da60 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
1da70 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1da80 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1da90 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1daa0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1dab0 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
1dac0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
1dad0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1dae0 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
1daf0 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
1db00 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
1db10 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
1db20 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
1db30 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a  an UPDATE)..**.*
1db40 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1db50 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65  .** {F13711} The
1db60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1db70 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
1db80 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1db90 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
1dba0 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
1dbb0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1dbc0 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
1dbd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1dbe0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dbf0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
1dc00 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
1dc10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  e.**          a 
1dc20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
1dc30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1dc40 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1dc50 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1dc60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1dc70 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1dc80 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
1dc90 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
1dca0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1dcb0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
1dcc0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
1dcd0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
1dce0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
1dcf0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
1dd00 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1dd10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1dd20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1dd30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1dd40 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1dd50 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
1dd60 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1dd70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1dd80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1dd90 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1dda0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20  inated.** UTF16 
1ddb0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
1ddc0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1ddd0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1dde0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1ddf0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1de00 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1de10 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1de20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1de30 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1de40 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
1de50 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
1de60 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1de70 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1de80 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1de90 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1dea0 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
1deb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1dec0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1ded0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
1dee0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
1def0 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  next call sqlite
1df00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
1df10 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
1df20 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e  n_name16().** on
1df30 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1df40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
1df50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
1df60 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
1df70 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
1df80 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
1df90 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
1dfa0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
1dfb0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
1dfc0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
1dfd0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1dfe0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1dff0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1e000 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1e010 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1e020 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1e030 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1e040 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1e050 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1e060 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1e070 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1e080 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1e090 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1e0a0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1e0b0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1e0c0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1e0d0 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
1e0e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1e0f0 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63  * {F13721} A suc
1e100 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1e110 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
1e120 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e130 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
1e140 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1e150 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
1e160 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
1e170 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
1e180 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
1e190 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
1e1a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e1b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
1e1c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e1d0 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
1e1e0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1e1f0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1e200 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ng..**.** {F1372
1e210 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
1e220 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
1e230 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1e240 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
1e250 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1e260 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1e270 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
1e280 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    of the Nth col
1e290 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20  umn (where 0 is 
1e2a0 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  the left-most co
1e2b0 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a  lumn) for the.**
1e2c0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
1e2d0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
1e2e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
1e2f0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1e300 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e310 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1e320 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1e330 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
1e340 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
1e350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e360 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e370 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
1e380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1e390 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
1e3a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e3b0 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
1e3c0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1e3d0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1e3e0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1e3f0 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75  here normal retu
1e400 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
1e410 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68  * {F13725} If th
1e420 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1e430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e440 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
1e450 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e470 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
1e480 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
1e490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
1e4a0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
1e4b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e4c0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  .** .** {F13726}
1e4d0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1e4e0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1e4f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1e500 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
1e510 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1e520 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1e530 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1e540 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
1e550 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
1e560 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
1e570 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
1e580 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
1e590 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1e5a0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
1e5b0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
1e5c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
1e5d0 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
1e5e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
1e5f0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1e600 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
1e610 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
1e620 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
1e630 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
1e640 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a  e indentifier.**
1e650 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
1e660 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
1e670 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
1e680 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1e690 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1e6a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1e6b0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1e6c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e6d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1e6e0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1e6f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1e700 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1e710 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1e720 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13740}.**.** Th
1e730 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
1e740 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
1e750 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
1e760 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
1e770 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
1e780 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
1e790 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1e7a0 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
1e7b0 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
1e7c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1e7d0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
1e7e0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
1e7f0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
1e800 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  a UTF8 or UTF16 
1e810 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
1e820 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
1e830 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
1e840 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
1e850 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
1e860 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
1e870 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
1e880 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
1e890 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1e8a0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
1e8b0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1e8c0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
1e8d0 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70  til.** the [prep
1e8e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e8f0 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
1e900 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1e910 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1e920 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
1e930 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
1e940 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
1e950 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
1e960 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
1e970 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1e980 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1e990 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1e9a0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1e9b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1e9c0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1e9d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1e9e0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
1e9f0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b  ing calls is a [
1ea00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ea10 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
1ea20 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1ea30 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1ea40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1ea50 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1ea60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
1ea70 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1ea80 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1ea90 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
1eaa0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1eab0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1eac0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
1ead0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
1eae0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
1eaf0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
1eb00 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
1eb10 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
1eb20 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
1eb30 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
1eb40 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
1eb50 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
1eb60 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
1eb70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1eb80 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
1eb90 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
1eba0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
1ebb0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
1ebc0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
1ebd0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1ebe0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
1ebf0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
1ec00 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
1ec10 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
1ec20 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
1ec30 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
1ec40 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
1ec50 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
1ec60 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
1ec70 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
1ec80 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
1ec90 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
1eca0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
1ecb0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
1ecc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1ecd0 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42   .** SQLITE_ENAB
1ece0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1ecf0 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1ed00 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1ed10 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a  **.** {U13751}.*
1ed20 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1ed30 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1ed40 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1ed50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1ed60 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1ed70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ed80 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1ed90 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1eda0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1edb0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1edc0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1edd0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  TS:.**.** {F1374
1ede0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1edf0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1ee00 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1ee10 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1ee20 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1ee30 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
1ee40 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1ee50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1ee60 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1ee70 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1ee80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1ee90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eea0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1eeb0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1eec0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1eed0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1eee0 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1eef0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1ef00 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1ef10 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1ef20 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1ef30 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1ef40 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1ef50 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d      .** {F13742}
1ef60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1ef70 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1ef80 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1ef90 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1efa0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1efb0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1efc0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1efd0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1efe0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1eff0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
1f000 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
1f010 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
1f020 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
1f030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f040 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
1f050 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
1f060 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
1f070 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1f080 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1f090 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1f0a0 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1f0b0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1f0c0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1f0d0 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1f0e0 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1f0f0 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20     .** {F13743} 
1f100 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1f110 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
1f120 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1f130 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1f140 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1f150 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1f160 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1f170 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1f180 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1f190 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1f1a0 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1f1b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1f1c0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1f1d0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1f1e0 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1f1f0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1f200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1f210 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1f220 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1f230 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1f240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1f250 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1f260 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1f270 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  F13744} The [sql
1f280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1f290 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
1f2a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f2b0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1f2c0 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1f2d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1f2e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1f2f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1f300 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1f310 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f320 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f330 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f350 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f360 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f370 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f380 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f390 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f3a0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f3b0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f3c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f3d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f3e0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f3f0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f400 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d      .** {F13745}
1f410 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f420 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f430 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1f440 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1f450 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f460 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1f470 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1f480 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
1f490 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f4a0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f4b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f4c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f4d0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f4e0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f4f0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f500 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f510 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f520 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f530 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f540 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f550 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f560 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f570 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f580 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d      .** {F13746}
1f590 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f5a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f5b0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1f5c0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1f5d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1f5e0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1f5f0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1f600 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1f610 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1f620 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1f630 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f640 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f650 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f670 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f680 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f690 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f6a0 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f6b0 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f6c0 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f6d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f6e0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f6f0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f700 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f710 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f720 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38       .** {F13748
1f730 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
1f740 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
1f750 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1f760 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f770 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1f780 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1f790 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
1f7a0 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  alid.**         
1f7b0 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
1f7c0 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
1f7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1f7e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1f7f0 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
1f800 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
1f810 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
1f820 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1f830 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
1f840 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
1f850 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1f860 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  lumn..**.** LIMI
1f870 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
1f880 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  U13751} If two o
1f890 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1f8a0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1f8b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f8c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1f8d0 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1f8e0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1f8f0 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1f900 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70    the same [prep
1f910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f920 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
1f930 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
1f940 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1f950 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1f960 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1f970 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1f980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1f990 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
1f9a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1f9b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f9d0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
1f9e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1f9f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1fa00 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1fa10 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fa20 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fa30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fa40 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1fa50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1fa60 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1fa70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fa80 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
1fa90 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1faa0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fab0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1fac0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1fad0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1fae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
1faf0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
1fb00 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
1fb10 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13760}.**.** 
1fb20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fb30 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
1fb40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  ed statement]. .
1fb50 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1fb60 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
1fb70 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1fb80 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1fb90 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
1fba0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
1fbb0 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
1fbc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1fbd0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1fbe0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1fbf0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1fc00 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1fc10 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1fc20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1fc30 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1fc40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1fc50 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1fc60 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1fc70 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1fc80 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1fc90 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1fca0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1fcb0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1fcc0 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f  d.  {END} .** Fo
1fcd0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
1fce0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1fcf0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1fd00 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1fd10 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
1fd20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1fd30 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
1fd40 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1fd50 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1fd60 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
1fd70 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
1fd80 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
1fd90 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
1fda0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
1fdb0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
1fdc0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
1fdd0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
1fde0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
1fdf0 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
1fe00 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1fe10 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
1fe20 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
1fe30 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
1fe40 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
1fe50 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
1fe60 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
1fe70 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
1fe80 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
1fe90 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
1fea0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
1feb0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
1fec0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
1fed0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
1fee0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
1fef0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
1ff00 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
1ff10 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
1ff20 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
1ff30 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
1ff40 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
1ff50 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
1ff60 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
1ff70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1ff80 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  F13761}  A succe
1ff90 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1ffa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1ffb0 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20  cltype(S,N)].** 
1ffc0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
1ffd0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
1ffe0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1fff0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
20000 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
20010 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
20020 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
20030 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
20040 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
20050 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
20060 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
20070 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
20080 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
20090 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
200a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
200b0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32  S..**.** {F13762
200c0 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
200d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
200e0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
200f0 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
20100 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
20110 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20120 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
20130 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a  te order string.
20140 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e  **           con
20150 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
20160 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66  ared datatype of
20170 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20180 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a  n that appears.*
20190 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
201a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
201b0 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20  umbered from 0) 
201c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
201d0 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
201e0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
201f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
20200 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66  .** {F13763}  If
20210 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
20220 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65  0 or N is greate
20230 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
20240 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
20250 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
20260 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72  lumns in [prepar
20270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
20280 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
20290 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
202a0 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
202b0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
202c0 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
202d0 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
202e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69  able column or i
202f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
20300 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
20310 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
20320 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
20330 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
20340 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
20350 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20360 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20370 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
20380 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20390 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
203a0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
203b0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
203c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
203d0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
203e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
203f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
20410 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
20420 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
20430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
20440 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
20450 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30  tatement {F13200
20460 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  }.**.** After an
20470 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20480 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
20490 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63  repared with a c
204a0 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72  all.** to either
204b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
204c0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
204d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
204e0 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66  ()] or to one of
204f0 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69  .** the legacy i
20500 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
20510 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
20520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20530 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  e16()],.** then 
20540 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
20550 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
20560 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
20570 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a  o evaluate the .
20580 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ** statement..**
20590 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
205a0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
205b0 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  of this sqlite3_
205c0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
205d0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
205e0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
205f0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
20600 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
20610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
20620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20630 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20650 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
20660 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
20670 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
20680 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
20690 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
206a0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
206b0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
206c0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
206d0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
206e0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
206f0 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
20700 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
20710 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
20720 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
20730 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20  * In the lagacy 
20740 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
20750 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
20760 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
20770 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53  TE_BUSY], .** [S
20780 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
20790 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
207a0 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
207b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
207c0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
207d0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
207e0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c  f the other [SQL
207f0 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
20800 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  code].** or [SQL
20810 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
20820 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
20830 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20   code] might be 
20840 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77  returned as.** w
20850 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
20860 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
20870 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
20880 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
20890 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
208a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
208b0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
208c0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
208d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
208e0 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20   a COMMIT.** or 
208f0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
20900 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
20910 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
20920 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
20930 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
20940 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
20950 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49  t is not a COMMI
20960 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  T and occurs wit
20970 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
20980 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
20990 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
209a0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
209b0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
209c0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
209d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
209e0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
209f0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
20a00 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
20a10 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
20a20 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
20a30 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
20a40 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
20a50 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
20a60 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
20a70 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
20a80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20a90 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
20aa0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20ab0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
20ac0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
20ad0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
20ae0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
20af0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
20b00 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20   data, then .** 
20b10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20  [SQLITE_ROW] is 
20b20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
20b30 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
20b40 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a  data is ready.**
20b50 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
20b60 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54  by the caller. T
20b70 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
20b80 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a   accessed using.
20b90 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
20ba0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c  column_int | col
20bb0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20bc0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20bd0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
20be0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
20bf0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
20c00 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a  w of data..** .*
20c10 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
20c20 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
20c30 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
20c40 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
20c50 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
20c60 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
20c70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
20c80 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
20c90 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
20ca0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
20cb0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
20cc0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
20cd0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20ce0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
20cf0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20d00 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
20d10 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  ic error code (e
20d20 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49  xample:.** [SQLI
20d30 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
20d40 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
20d50 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
20d60 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
20d70 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
20d80 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
20d90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20da0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
20db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
20dc0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
20dd0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
20de0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
20df0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
20e00 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
20e10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
20e20 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
20e30 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
20e40 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
20e50 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
20e60 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
20e70 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
20e80 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
20e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20ea0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
20eb0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
20ec0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
20ed0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
20ee0 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
20ef0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
20f00 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
20f10 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
20f20 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
20f30 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
20f40 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
20f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20f60 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
20f70 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
20f80 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
20f90 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
20fa0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
20fb0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
20fc0 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
20fd0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
20fe0 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
20ff0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
21000 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
21010 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
21020 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
21030 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
21040 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
21050 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21060 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
21070 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21080 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
21090 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
210a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
210b0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
210c0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
210d0 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
210e0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
210f0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
21100 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21110 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
21120 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
21130 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
21140 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
21150 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
21160 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21170 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
21180 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
21190 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
211a0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
211b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
211c0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
211d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
211e0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
211f0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
21200 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
21210 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
21220 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
21230 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
21240 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
21250 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
21260 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
21270 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
21280 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
21290 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
212a0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
212b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
212c0 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49  *.** {F13202}  I
212d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
212e0 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
212f0 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20  y to be.**      
21300 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b       run, then [
21310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21320 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
21330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21340 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75  t.**           u
21350 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69  ntil to completi
21360 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
21370 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
21380 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20  n another.**    
21390 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68         row of th
213a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20  e result set or 
213b0 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20  an interrupt or 
213c0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
213d0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ccurs..**.** {F1
213e0 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
213f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
21400 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
21410 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
21420 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21430 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74  ment] S to run t
21440 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a  o completion,.**
21450 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
21460 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
21470 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
21480 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57  *.** {F15306}  W
21490 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
214a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
214b0 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
214c0 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20   is ready.**    
214d0 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e         to return
214e0 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
214f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
21500 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  it returns.**   
21510 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
21520 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ROW]..**.** {F15
21530 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
21540 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
21550 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
21560 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
21570 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
21580 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72  pt|interrupt] or
21590 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
215a0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
215b0 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
215c0 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20  propraite error 
215d0 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
215e0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
215f0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
21600 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
21610 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
21620 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d  ..**.** {F15310}
21630 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
21640 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72  _interrupt|inter
21650 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d  rupt] or run-tim
21660 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
21670 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
21680 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
21690 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
216a0 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
216b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
216c0 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
216d0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
216e0 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
216f0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
21700 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
21710 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21720 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
21730 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
21740 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  n returns either
21750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
21760 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53  QLITE_ERROR], [S
21770 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20  QLITE_BUSY], or 
21780 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
21790 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
217a0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
217b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
217c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
217d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
217e0 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d  ult set {F13770}
217f0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
21800 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
21810 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
21820 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
21830 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  ult set..**.** I
21840 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21850 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72   {F13771}  After
21860 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21870 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61  te3_step(S)] tha
21880 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  t returns.**    
21890 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
218a0 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  OW], the [sqlite
218b0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
218c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
218d0 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
218e0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
218f0 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
21900 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
21910 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
21920 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
21930 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  F13772}  After [
21940 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21950 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
21960 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
21970 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
21980 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
21990 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
219a0 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
219b0 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n .**           
219c0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70  called on the [p
219d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
219e0 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  t] for.**       
219f0 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69      the first ti
21a00 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20  me since it was 
21a10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21a20 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20  |prepared].**   
21a30 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
21a40 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d  te3_reset|reset]
21a50 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  , the [sqlite3_d
21a60 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a  ata_count(S)].**
21a70 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69             routi
21a80 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
21a90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21aa0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
21ab0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
21ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21ad0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
21ae0 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d  tatypes {F10265}
21af0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21b00 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21b10 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61  {F10266}Every va
21b20 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
21b30 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
21b40 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
21b50 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
21b60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
21b70 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
21b80 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
21b90 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
21ba0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
21bb0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
21bc0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
21bd0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
21be0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
21bf0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
21c00 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
21c10 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
21c20 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
21c30 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
21c40 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
21c50 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
21c60 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
21c70 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
21c80 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
21c90 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
21ca0 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
21cb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
21cc0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
21cd0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
21ce0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f   SQLITE3_TEXT no
21cf0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
21d00 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
21d10 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
21d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
21d30 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
21d40 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
21d50 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
21d60 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
21d70 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
21d80 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
21d90 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
21da0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
21db0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
21dc0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
21dd0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
21de0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20  PI3REF: Results 
21df0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
21e00 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a  ery {F13800}.**.
21e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
21e20 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
21e30 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e  lt set query" in
21e40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
21e50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
21e60 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
21e70 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67   about.** a sing
21e80 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
21e90 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
21ea0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
21eb0 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
21ec0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
21ed0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
21ee0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72  r to the .** [pr
21ef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21f00 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a  ] that is being.
21f10 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ** evaluated (th
21f20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
21f30 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ] that was retur
21f40 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
21f50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21f60 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
21f70 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a  s variants) and.
21f80 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
21f90 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
21fa0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
21fb0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
21fc0 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75  rmation .** shou
21fd0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
21fe0 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
21ff0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
22000 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61  ult set.** has a
22010 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a  n index of 0..**
22020 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
22030 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
22040 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
22050 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
22060 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  or if the.** the
22070 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
22080 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
22090 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
220a0 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73  efined. .** Thes
220b0 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
220c0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
220d0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
220e0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
220f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
22100 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
22110 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
22120 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
22130 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
22140 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22150 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
22160 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
22170 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
22180 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
22190 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
221a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
221b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
221c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
221d0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
221e0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
221f0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
22200 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22210 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
22220 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
22230 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
22240 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
22250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
22260 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22270 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
22280 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
22290 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
222a0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
222b0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
222c0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
222d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
222e0 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  fined.  .**.** T
222f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22300 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
22310 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
22320 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
22330 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
22340 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
22350 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
22360 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
22370 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
22380 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
22390 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
223a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
223b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
223c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
223d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
223e0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
223f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
22400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
22410 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
22420 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
22430 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
22440 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
22450 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
22460 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
22470 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
22480 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
22490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
224a0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
224b0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
224c0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
224d0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
224e0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
224f0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
22500 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
22510 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
22520 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
22530 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
22540 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
22550 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
22560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22570 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69  ytes() .** routi
22580 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
22590 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
225a0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
225b0 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
225c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
225d0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
225e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
225f0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
22600 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
22610 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
22620 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22630 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
22640 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
22650 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
22660 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
22670 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
22680 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
22690 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
226a0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
226b0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
226c0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
226d0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
226e0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
226f0 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
22700 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
22710 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
22720 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22730 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
22740 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
22750 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
22760 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
22770 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
22780 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
22790 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
227a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
227b0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
227c0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
227d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
227e0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
227f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
22800 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
22810 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
22820 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
22830 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
22840 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
22850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22860 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
22870 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20  -length blob is 
22880 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
22890 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
228a0 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
228b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
228c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
228d0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
228e0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
228f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22900 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
22910 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
22920 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
22930 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
22940 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
22950 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74    .** The zero t
22960 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
22970 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
22980 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
22990 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
229a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
229b0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
229c0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
229d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
229e0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
229f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22a00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22a10 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
22a20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
22a30 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
22a40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
22a50 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
22a60 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
22a70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22a80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
22a90 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
22aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
22ab0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
22ac0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
22ad0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
22ae0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
22af0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
22b00 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
22b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
22b20 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
22b30 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
22b40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
22b50 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
22b60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
22b70 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
22b80 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
22b90 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
22ba0 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
22bb0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
22bc0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
22bd0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
22be0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
22bf0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
22c00 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
22c10 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
22c20 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
22c30 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
22c40 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
22c50 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
22c60 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
22c70 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
22c80 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
22c90 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
22ca0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
22cb0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
22cc0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
22cd0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
22ce0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
22cf0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
22d00 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
22d10 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
22d20 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22d30 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
22d40 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22d50 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
22d60 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
22d70 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
22d80 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
22d90 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
22da0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
22db0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
22dc0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
22dd0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
22de0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
22df0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
22e00 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
22e10 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
22e20 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
22e30 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
22e40 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
22e50 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
22e60 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
22e70 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
22e80 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
22e90 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
22ea0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
22eb0 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
22ec0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
22ed0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
22ee0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
22ef0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
22f00 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
22f10 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
22f20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
22f30 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
22f40 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
22f50 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
22f60 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
22f70 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
22f80 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
22f90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
22fa0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
22fb0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
22fc0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
22fd0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
22fe0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
22ff0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
23000 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
23010 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23020 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
23030 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23040 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
23050 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
23060 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
23070 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23080 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
23090 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
230a0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
230b0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
230c0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
230d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
230e0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
230f0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
23100 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
23110 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
23120 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
23130 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
23140 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
23150 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
23160 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
23170 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23180 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23190 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
231a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
231b0 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
231c0 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
231d0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
231e0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
231f0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
23200 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
23210 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
23220 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
23230 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
23240 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
23250 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
23260 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
23270 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
23280 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
23290 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
232a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
232b0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
232c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
232d0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
232e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
232f0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
23300 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
23310 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
23320 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
23330 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
23340 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
23350 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
23360 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23370 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
23380 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
23390 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
233a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
233b0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
233c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
233d0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
233e0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
233f0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
23400 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
23410 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
23420 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
23430 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
23440 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
23450 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
23460 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
23470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23480 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
23490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
234a0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
234b0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
234c0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
234d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
234e0 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
234f0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
23500 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
23510 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
23520 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
23530 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
23540 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
23550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23560 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
23570 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
23580 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
23590 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
235a0 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
235b0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
235c0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
235d0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
235e0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
235f0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
23600 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
23610 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
23620 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
23630 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
23640 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
23650 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
23660 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
23670 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
23680 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
23690 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
236a0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
236b0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
236c0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
236d0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
236e0 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
236f0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
23700 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
23710 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
23720 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
23730 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
23740 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
23750 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
23760 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
23770 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
23780 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23790 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
237a0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
237b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
237c0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
237d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
237e0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
237f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
23800 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
23810 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
23820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
23830 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
23840 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23850 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
23860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23870 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
23880 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
23890 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
238a0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
238b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
238c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
238d0 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
238e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
238f0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
23900 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
23910 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
23920 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
23930 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
23940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23950 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
23960 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23970 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
23980 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
23990 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
239a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
239b0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
239c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
239d0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
239e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
239f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
23a00 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
23a10 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
23a20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23a30 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
23a40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a50 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
23a60 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
23a70 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
23a80 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
23a90 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
23aa0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
23ab0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
23ac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23ad0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23ae0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23af0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
23b00 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
23b10 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
23b20 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
23b30 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
23b40 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
23b50 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
23b60 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
23b70 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
23b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23b90 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
23ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23bb0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a  ()], etc. into .
23bc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
23bd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
23be0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
23bf0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
23c00 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
23c10 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
23c20 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23c30 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
23c40 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
23c50 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
23c60 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
23c70 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
23c80 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
23c90 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
23ca0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
23cb0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
23cc0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
23cd0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
23ce0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
23cf0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
23d00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23d10 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20  ** {F13803} The 
23d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23d30 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
23d40 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
23d50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
23d60 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
23d70 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
23d80 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
23d90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
23da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23db0 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62  t] S into a blob
23dc0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
23dd0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
23de0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
23df0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
23e00 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54  **.** {F13806} T
23e10 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23e20 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69  mn_bytes(S,N)] i
23e30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23e40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23e50 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23e60 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
23e70 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
23e80 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
23e90 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
23ea0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
23eb0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
23ec0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
23ed0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
23ee0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
23ef0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23f00 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  b(S,N)] or.**   
23f10 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
23f20 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
23f30 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39  ]..**.** {F13809
23f40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23f50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c  olumn_bytes16(S,
23f60 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
23f70 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
23f80 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
23f90 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
23fa0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
23fb0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
23fc0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
23fd0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
23fe0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
23ff0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
24000 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
24010 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
24020 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24030 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
24040 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13812} The [sqli
24050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
24060 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24070 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
24080 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24090 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
240a0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
240b0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
240c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
240d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
240e0 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
240f0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
24100 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
24110 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
24120 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
24130 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b  * {F13815} The [
24140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24150 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
24160 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
24170 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24180 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24190 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
241a0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
241b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
241c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
241d0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
241e0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
241f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
24200 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
24210 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
24220 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
24230 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
24240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24250 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
24260 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
24270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24280 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24290 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
242a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
242b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
242c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
242d0 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
242e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
242f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24300 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
24310 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
24320 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20  .**.** {F13821} 
24330 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24340 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
24350 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
24360 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
24370 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
24380 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24390 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
243a0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
243b0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
243c0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
243d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
243e0 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
243f0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
24400 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
24410 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
24420 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54  **.** {F13824} T
24430 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24440 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
24450 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
24460 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
24470 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
24480 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
24490 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
244a0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
244b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
244c0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
244d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
244e0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
244f0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
24500 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
24510 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
24520 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
24530 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
24540 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
24550 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65  .** {F13827} The
24560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24570 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
24580 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
24590 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
245a0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
245b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
245c0 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
245d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
245e0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
245f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
24600 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
24610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
24620 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
24630 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
24640 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24650 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24670 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
24680 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  F13830} The [sql
24690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
246a0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
246b0 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
246c0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
246d0 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
246e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
246f0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
24700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24710 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24720 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
24730 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24760 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
24770 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24780 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
24790 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
247a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
247b0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
247c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
247d0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
247e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
247f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24800 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
24810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24820 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
24830 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24840 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24850 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
24860 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24870 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
24880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24890 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
248a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
248b0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
248c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
248d0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
248e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
248f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24910 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
24920 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24930 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24940 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
24950 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
24970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24980 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
24990 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
249a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
249b0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
249c0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
249d0 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a  ct {F13300}.**.*
249e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
249f0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
24a00 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
24a10 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65  elete a .** [pre
24a20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24a30 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  . If the stateme
24a40 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74  nt was.** execut
24a50 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  ed successfully,
24a60 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
24a70 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51   at all, then SQ
24a80 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
24a90 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75  ned..** If execu
24aa0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
24ab0 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
24ac0 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  n an .** [error 
24ad0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
24ae0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  ed error code].*
24af0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a  * is returned. .
24b00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
24b10 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
24b20 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
24b30 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
24b40 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
24b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24b60 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
24b70 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
24b80 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  ot .** completed
24b90 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
24ba0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24bb0 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
24bc0 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
24bd0 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
24be0 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20   an interrupt.  
24bf0 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  (See [sqlite3_in
24c00 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a  terrupt()].) .**
24c10 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
24c20 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
24c30 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
24c40 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65  actions cancelle
24c50 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  d,  .** dependin
24c60 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
24c70 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20  tances, and the 
24c80 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
24c90 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
24ca0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
24cb0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
24cc0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  TS:.**.** {F1130
24cd0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
24ce0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
24cf0 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
24d00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24d10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24d20 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
24d30 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
24d40 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
24d50 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
24d60 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
24d70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34  t..**.** {F11304
24d80 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
24d90 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
24da0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
24db0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
24dc0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24dd0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
24de0 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
24df0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
24e00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24e10 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
24e20 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
24e30 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
24e40 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
24e50 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
24e60 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
24e70 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
24e80 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
24e90 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13330}.**.** The
24ea0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
24eb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
24ec0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a  led to reset a .
24ed0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
24ee0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
24ef0 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ** back to its i
24f00 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
24f10 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
24f20 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
24f30 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
24f40 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
24f50 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
24f60 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
24f70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24f80 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
24f90 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
24fa0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
24fb0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
24fc0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
24fd0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
24fe0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
24ff0 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {F11332} The [sq
25000 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25010 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
25020 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25030 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
25040 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
25050 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
25060 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
25070 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20  .** {F11334} If 
25080 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25090 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
250a0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a  _step(S)] for .*
250b0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
250c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
250d0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
250e0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
250f0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
25100 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
25110 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
25120 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
25130 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
25140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
25150 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
25160 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
25170 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
25180 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {F11336} If the 
25190 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
251a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
251b0 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  p(S)] for.**    
251c0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
251d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
251e0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
251f0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
25200 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
25210 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
25220 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
25230 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
25240 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71  {F11338} The [sq
25250 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25260 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
25270 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
25280 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
25290 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
252a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
252b0 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65  ngs] on [prepare
252c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
252d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
252e0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
252f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25300 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
25310 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
25320 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  QL Functions {F1
25330 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  6100}.** KEYWORD
25340 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
25350 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20  ation routines} 
25360 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
25370 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
25380 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
25390 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63  s.** "function c
253a0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
253b0 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ") are used to a
253c0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
253d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a   or aggregates.*
253e0 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  * or to redefine
253f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
25400 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
25410 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25420 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64  gates.  The.** d
25430 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62  ifference only b
25440 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69  etween the two i
25450 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
25460 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
25470 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
25480 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
25490 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
254a0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
254b0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
254c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
254d0 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20  on() and UTF-16 
254e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
254f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
25500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25510 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25520 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25530 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
25540 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25550 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
25560 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
25570 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
25580 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
25590 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
255a0 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79  tion] internally
255b0 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75  , then SQL.** fu
255c0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
255d0 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
255e0 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61  ly to each [data
255f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
25610 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
25620 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25630 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
25640 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72  be created.** or
25650 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   redefined..** T
25660 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25670 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
25680 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
25690 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
256a0 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  .** zero-termina
256b0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
256c0 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
256d0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
256e0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
256f0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
25700 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
25710 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
25720 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
25730 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ll result in an 
25740 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72  SQLITE_ERROR err
25750 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  or..**.** The th
25760 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
25770 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
25780 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
25790 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
257a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
257b0 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
257c0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
257d0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
257e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
257f0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
25800 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
25810 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
25820 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
25830 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
25840 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
25850 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  t .** [SQLITE_UT
25860 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
25870 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
25880 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
25890 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
258a0 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
258b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
258c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
258d0 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
258e0 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
258f0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
25900 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
25910 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25920 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
25930 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
25940 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
25950 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
25960 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
25970 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
25980 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25990 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
259a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
259b0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
259c0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
259d0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
259e0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
259f0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
25a00 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
25a10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25a20 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
25a30 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
25a40 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
25a50 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
25a60 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
25a70 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
25a80 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
25a90 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
25aa0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
25ab0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25ac0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
25ad0 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74  are what.** text
25ae0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
25af0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
25b00 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
25b10 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  ld be.** [SQLITE
25b20 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
25b30 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
25b40 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
25b50 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
25b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25b70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
25b80 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
25b90 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
25ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
25bb0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
25bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
25bd0 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
25be0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
25bf0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
25c00 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
25c10 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
25c20 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
25c30 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25c40 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25c50 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25c60 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
25c70 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
25c80 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
25c90 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ion of.** the xF
25ca0 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  unc callback onl
25cb0 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
25cc0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25cd0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a  d as the xStep.*
25ce0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72  * and xFinal par
25cf0 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
25d00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
25d10 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
25d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25d30 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46   of xStep and xF
25d40 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
25d50 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
25d60 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
25d70 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69  ete an.** existi
25d80 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ng SQL function 
25d90 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
25da0 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
25db0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
25dc0 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  * callback..**.*
25dd0 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
25de0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
25df0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
25e00 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25e10 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
25e20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
25e30 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
25e40 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
25e50 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
25e60 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
25e70 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74  g perferred text
25e80 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
25e90 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
25ea0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
25eb0 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
25ec0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
25ed0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
25ee0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
25ef0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
25f00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
25f10 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
25f20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25f30 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
25f40 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
25f50 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
25f60 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
25f70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
25f80 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
25f90 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
25fa0 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
25fb0 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
25fc0 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
25fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
25fe0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
25ff0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
26000 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
26010 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
26020 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
26030 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
26040 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  F16106} A succes
26050 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26060 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
26070 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26080 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26090 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
260a0 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
260b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
260c0 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
260d0 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74  unctions in [dat
260e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
260f0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
26100 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
26110 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
26120 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
26130 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
26140 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
26150 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64 20  ing a perferred 
26160 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
26170 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30   E..**.** {F1610
26180 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
26190 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
261a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
261b0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
261c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
261d0 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
261e0 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
261f0 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
26200 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
26210 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
26220 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
26230 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  values..**.** {F
26240 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
26250 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26260 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
26270 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
26280 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
26290 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
262a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
262b0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
262c0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
262d0 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
262e0 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
262f0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
26300 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26310 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20  .**.** {F16118} 
26320 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
26330 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
26340 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
26350 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
26360 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
26370 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
26380 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
26390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
263a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
263b0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
263c0 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
263d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
263e0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54  **.** {F16121} T
263f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26400 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
26410 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
26420 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
26430 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
26440 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
26450 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
26460 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
26470 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
26480 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
26490 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
264a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
264b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d  ..**.** {F16124}
264c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
264d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
264e0 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
264f0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
26500 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
26510 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
26520 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
26530 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
26540 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
26550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
26560 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
26570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
26580 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
26590 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
265a0 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
265b0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
265c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20  .**.** {F16127} 
265d0 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
265e0 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
265f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26600 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
26610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
26620 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
26630 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
26640 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
26650 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
26660 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
26670 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
26680 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
26690 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
266a0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
266b0 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
266c0 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {F16130} When N 
266d0 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
266e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
266f0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
26700 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
26710 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
26720 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
26730 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
26740 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
26750 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
26760 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
26770 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
26780 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20  * {F16133} When 
26790 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
267a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
267b0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
267c0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
267d0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
267e0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
267f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26800 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
26810 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
26820 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
26830 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
26840 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
26850 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
26860 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
26870 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
26880 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
26890 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {F16136} When c
268a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
268b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
268c0 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
268d0 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
268e0 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
268f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26900 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26910 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
26920 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
26930 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26940 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
26950 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
26960 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
26970 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
26980 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
26990 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
269a0 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
269b0 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
269c0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
269d0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
269e0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
269f0 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
26a00 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
26a10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26a20 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26a30 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
26a40 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  ializer.**      
26a50 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
26a60 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
26a70 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
26a80 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
26a90 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
26aa0 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
26ab0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
26ac0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32  s..**.** {F16142
26ad0 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
26ae0 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
26af0 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
26b00 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
26b10 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
26b20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26b30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
26b40 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
26b50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
26b60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26b70 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
26b80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26b90 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
26ba0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
26bb0 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
26bc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26bd0 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
26be0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
26bf0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
26c00 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
26c10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26c20 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
26c30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26c40 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
26c50 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
26c60 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
26c70 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
26c80 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
26c90 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
26ca0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
26cb0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26cc0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26cd0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26ce0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
26cf0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
26d00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
26d10 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
26d20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26d30 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
26d40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26d50 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
26d60 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
26d70 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26d80 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26d90 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26da0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26db0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
26dc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26de0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
26df0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26e00 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26e10 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26e20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26e30 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
26e40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26e50 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
26e60 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10267}.**.** Th
26e70 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
26e80 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
26e90 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
26ea0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
26eb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
26ec0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
26ed0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
26ee0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
26ef0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
26f00 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
26f10 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26f20 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
26f30 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
26f40 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
26f50 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
26f60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26f70 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
26f80 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
26f90 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
26fa0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26fb0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
26fc0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26fd0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
26fe0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
26ff0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
27000 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
27010 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
27020 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
27030 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
27040 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
27050 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
27060 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
27070 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27080 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
27090 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
270a0 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
270b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
270c0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
270d0 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
270e0 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
270f0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
27100 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
27110 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
27120 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
27130 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
27140 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
27150 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
27160 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
27170 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
27180 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27190 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
271a0 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
271b0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
271c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
271d0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
271e0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
271f0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
27200 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
27210 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
27220 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
27230 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
27240 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69  cleanup(void);.i
27250 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
27260 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
27270 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
27280 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
27290 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
272a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
272b0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
272c0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
272d0 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d   Values {F15100}
272e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
272f0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
27300 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
27310 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27320 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
27330 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
27340 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
27350 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
27360 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
27370 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
27380 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
27390 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
273a0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
273b0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
273c0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
273d0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
273e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
273f0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
27400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27410 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
27420 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
27430 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
27440 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
27450 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
27460 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
27470 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
27480 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
27490 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
274a0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
274b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
274c0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
274d0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
274e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
274f0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
27500 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
27510 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
27520 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
27530 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
27540 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
27550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27560 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
27570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27580 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
27590 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
275a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
275b0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
275c0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
275d0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
275e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
275f0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
27600 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
27610 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
27620 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27630 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
27640 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
27650 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
27660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
27670 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
27680 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
27690 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
276a0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
276b0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
276c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
276d0 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  ue] object point
276e0 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  er.** instead of
276f0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
27700 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
27710 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
27720 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
27730 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27740 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
27750 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
27760 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF16 string.** 
27770 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27780 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
27790 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54  host machine.  T
277a0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
277b0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
277c0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
277d0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
277e0 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
277f0 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20  t UTF16 strings 
27800 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
27810 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
27820 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
27830 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27840 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
27850 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
27860 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
27870 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
27880 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27890 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
278a0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
278b0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
278c0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
278d0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
278e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
278f0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
27900 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
27910 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
27920 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
27930 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
27940 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65  rds if the value
27950 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
27960 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27970 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
27980 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
27990 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73   done.  Otherwis
279a0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
279b0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a  occurs.  The .**
279c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
279d0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
279e0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
279f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27a00 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27a10 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27a20 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27a30 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  t the pointer th
27a40 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  at.** is returne
27a50 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
27a60 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
27a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27a80 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
27a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27aa0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
27ab0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
27ac0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
27ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
27ae0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
27af0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27b00 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
27b10 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
27b20 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
27b30 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20  alue_text16()]. 
27b40 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f   .**.** These ro
27b50 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
27b60 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
27b70 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
27b80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27b90 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
27ba0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
27bb0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
27bc0 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  .**.**.** INVARI
27bd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ANTS:.**.** {F15
27be0 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
27bf0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
27c00 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
27c10 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
27c20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
27c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27c40 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c  ject V into a bl
27c50 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  ob and then retu
27c60 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
27c70 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
27c80 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
27c90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d  ..**.** {F15106}
27ca0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
27cb0 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
27cc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27cd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
27ce0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27cf0 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  in the blob or s
27d00 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
27d10 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
27d20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
27d30 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
27d40 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
27d50 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
27d60 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
27d70 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
27d80 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
27d90 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
27da0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
27db0 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
27dc0 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b  * {F15109} The [
27dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27de0 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
27df0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
27e00 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
27e10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27e20 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
27e30 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
27e40 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
27e50 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
27e60 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
27e70 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
27e80 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
27e90 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
27ea0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27eb0 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
27ec0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27ed0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
27ee0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
27ef0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
27f00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31  )]..**.** {F1511
27f10 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
27f20 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
27f30 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
27f40 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
27f50 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
27f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27f70 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
27f80 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
27f90 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
27fa0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
27fb0 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
27fc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20  .**.** {F15115} 
27fd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
27fe0 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
27ff0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28000 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
28010 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28020 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
28030 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
28040 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
28050 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
28060 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
28070 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
28080 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
28090 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  F15118} The [sql
280a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
280b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
280c0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
280d0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
280e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
280f0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
28100 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
28110 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
28120 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
28130 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
28140 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
28150 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
28160 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
28170 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28180 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28190 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
281a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
281b0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
281c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
281d0 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
281e0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
281f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28200 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28210 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54  **.** {F15124} T
28220 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28230 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74  e_text16(V)] int
28240 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
28250 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28260 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
28270 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28280 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
28290 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
282a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
282b0 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
282c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
282d0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
282e0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
282f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
28300 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
28310 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  5127} The [sqlit
28320 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
28330 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
28340 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28350 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
28360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28370 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28380 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28390 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
283a0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
283b0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
283c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
283d0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
283e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
283f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
28400 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c  F15130} The [sql
28410 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28420 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6le(V)] interfac
28430 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
28440 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
28450 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28460 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
28470 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28480 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
28490 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
284a0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
284b0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
284c0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
284d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
284e0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
284f0 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65  .** {F15133} The
28500 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28510 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
28520 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
28530 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
28540 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
28550 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
28560 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
28570 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
28580 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
28590 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
285a0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
285b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
285c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
285d0 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
285e0 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  15136} The [sqli
285f0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
28600 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  c_type(V)] inter
28610 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  face converts.**
28620 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
28630 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28640 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
28650 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
28660 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20  integer or.**   
28670 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e         a floatin
28680 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66  g point value if
28690 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69   it can do so wi
286a0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a  thout loss of.**
286b0 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
286c0 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72  ation, and retur
286d0 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  ns one of [SQLIT
286e0 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20  E_NULL],.**     
286f0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54       [SQLITE_INT
28700 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
28710 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
28720 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  EXT], or.**     
28730 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f       [SQLITE_BLO
28740 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
28750 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
28760 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
28770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28780 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
28790 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
287a0 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
287b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
287c0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
287d0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
287e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
287f0 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
28800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28810 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
28820 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
28830 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
28840 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
28850 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28860 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
28870 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28880 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
288a0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
288b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
288c0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
288d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
288e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
288f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28900 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
28910 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28920 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28930 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28940 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
28950 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
28960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28970 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
28980 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28990 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
289a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
289b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
289c0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
289d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
289e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
289f0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
28a00 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
28a10 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a  xt {F16210}.**.*
28a20 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
28a30 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74  tion of aggregat
28a40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
28a50 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
28a60 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20   to allocate.** 
28a70 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  a structure for 
28a80 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
28a90 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69  ate.  .** The fi
28aa0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
28ab0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28ac0 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
28ad0 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64   is.** is called
28ae0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
28af0 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
28b00 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
28b10 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
28b20 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d  * zeros that mem
28b30 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
28b40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
28b50 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61  ..** On second a
28b60 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
28b70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
28b80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28b90 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
28ba0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
28bb0 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65  ction index, the
28bc0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
28bd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
28be0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
28bf0 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ** of the aggreg
28c00 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20  ate can use the 
28c10 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
28c20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
28c30 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
28c40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
28c50 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
28c60 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
28c70 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
28c80 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
28c90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28ca0 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
28cb0 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
28cc0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
28cd0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
28ce0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
28cf0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
28d00 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
28d10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
28d20 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
28d30 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
28d40 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
28d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
28d60 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
28d70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
28d80 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
28d90 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
28da0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
28db0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
28dc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28dd0 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65  .** {F16211} The
28de0 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
28df0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
28e00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28e10 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
28e20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
28e30 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
28e40 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
28e50 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
28e60 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
28e70 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
28e80 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
28e90 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65  llocation N byte
28ea0 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
28eb0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
28ec0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
28ed0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
28ee0 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  to the allocatio
28ef0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
28f00 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
28f10 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
28f20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
28f30 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
28f40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
28f50 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
28f60 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
28f70 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
28f80 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
28f90 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {F16215} Secon
28fa0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
28fb0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
28fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28fd0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28fe0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
28ff0 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
29000 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
29010 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
29020 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
29030 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
29040 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
29050 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
29060 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
29070 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
29080 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
29090 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65  .** {F16217} The
290a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
290b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
290c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
290d0 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
290e0 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
290f0 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
29100 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
29110 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
29120 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
29130 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29140 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
29150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29160 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
29170 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
29180 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
29190 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
291a0 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
291b0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
291c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
291d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
291e0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
291f0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
29200 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
29210 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a  ons {F16240}.**.
29220 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
29230 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
29240 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
29250 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
29260 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
29270 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
29280 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
29290 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
292a0 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
292b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
292c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
292d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
292e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
292f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
29300 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
29310 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29320 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
29330 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
29340 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
29350 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
29360 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
29370 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
29380 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29390 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
293a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
293b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
293c0 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {F16243} The [s
293d0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
293e0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
293f0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
29400 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29410 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
29420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
29430 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
29440 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
29450 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
29460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29470 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
29480 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
29490 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
294a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
294b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
294c0 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
294d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
294e0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
294f0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29500 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
29510 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
29520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
29530 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
29540 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
29550 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16250}.**.** T
29560 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
29570 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
29580 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29590 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
295a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
295b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
295c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
295d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
295e0 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
295f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29600 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
29610 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29620 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
29630 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
29640 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
29650 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29660 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
29670 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
29680 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
29690 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
296a0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
296b0 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
296c0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
296d0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
296e0 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
296f0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
29700 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
29710 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
29720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
29730 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29740 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
29750 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
29760 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
29770 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
29780 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
29790 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
297a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
297b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
297c0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
297d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
297e0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
297f0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
29800 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
29810 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
29820 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a  ta {F16270}.**.*
29830 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
29840 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
29850 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
29860 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
29870 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
29880 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
29890 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
298a0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
298b0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
298c0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
298d0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
298e0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
298f0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
29900 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
29910 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
29920 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
29930 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
29940 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
29950 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
29960 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
29970 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
29980 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
29990 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
299a0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
299b0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
299c0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
299d0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
299e0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
299f0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
29a00 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
29a10 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
29a20 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
29a30 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
29a40 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
29a50 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29a60 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
29a70 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
29a80 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
29a90 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
29aa0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
29ab0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
29ac0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
29ad0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
29ae0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
29af0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
29b00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
29b10 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
29b20 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
29b30 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
29b40 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
29b50 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
29b60 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
29b70 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
29b80 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
29b90 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
29ba0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29bb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
29bc0 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
29bd0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62   has been ever b
29be0 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
29bf0 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Nth.** argument 
29c00 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
29c10 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65   or if the coore
29c20 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
29c30 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68  n parameter.** h
29c40 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
29c50 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
29c60 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c  as set, then sql
29c70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
29c80 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
29c90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29ca0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29cb0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
29cc0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
29cd0 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70  e meta-data.** p
29ce0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
29cf0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
29d00 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  s the meta-data 
29d10 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
29d20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29d30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29d40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
29d50 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
29d60 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
29d70 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
29d80 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
29d90 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
29da0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
29db0 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69  yed. .** If it i
29dc0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
29dd0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
29de0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a  he destructor .*
29df0 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
29e00 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
29e10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29e20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
29e30 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61  n.** the meta-da
29e40 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
29e50 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
29e60 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
29e70 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
29e80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
29e90 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
29ea0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
29eb0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
29ec0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
29ed0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
29ee0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61  and drop meta-da
29ef0 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72  ta on.** any par
29f00 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
29f10 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
29f20 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
29f30 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68  arantee.** is th
29f40 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  at the destructo
29f50 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
29f60 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
29f70 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70  data is.** dropp
29f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
29f90 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
29fa0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
29fb0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
29fc0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
29fd0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
29fe0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
29ff0 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
2a000 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
2a010 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
2a020 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
2a030 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a040 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2a050 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a060 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2a070 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2a080 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2a090 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2a0a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d  :.**.** {F16272}
2a0b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
2a0c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
2a0d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a0e0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
2a0f0 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
2a100 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2a110 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
2a120 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2a130 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2a140 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
2a150 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
2a160 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
2a170 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2a180 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2a190 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
2a1a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eter..**.** {F16
2a1b0 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
2a1c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2a1d0 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
2a1e0 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
2a1f0 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
2a200 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
2a210 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2a220 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2a230 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
2a240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
2a250 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53  **.** {F16276} S
2a260 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2a270 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2a280 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2a290 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2a2a0 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
2a2b0 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
2a2c0 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
2a2d0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
2a2e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
2a2f0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2a300 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
2a310 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
2a320 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a330 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
2a340 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {F16277} SQLite 
2a350 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
2a360 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
2a370 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
2a380 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
2a390 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
2a3a0 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
2a3b0 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
2a3c0 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20  * {F16278} When 
2a3d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2a3e0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2a3f0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
2a400 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
2a410 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
2a420 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
2a430 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2a440 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
2a450 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2a460 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
2a470 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
2a480 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53  **.** {F16279} S
2a490 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
2a4a0 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
2a4b0 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
2a4c0 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
2a4d0 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
2a4e0 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
2a4f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
2a500 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
2a510 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2a520 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
2a530 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a540 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
2a550 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2a560 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2a570 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a580 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2a590 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2a5a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a5b0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2a5c0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2a5d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a5e0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2a5f0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2a600 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
2a610 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10280}.**.** T
2a620 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2a630 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
2a640 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2a650 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2a660 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2a670 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2a680 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2a690 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2a6a0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2a6b0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2a6c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2a6d0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2a6e0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2a6f0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2a700 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2a710 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2a720 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2a730 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
2a740 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2a750 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2a760 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2a770 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2a780 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2a790 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2a7a0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2a7b0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2a7c0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2a7d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2a7e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2a7f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2a800 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2a810 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2a820 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2a830 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2a840 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2a850 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2a860 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2a870 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2a880 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2a890 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2a8a0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2a8b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2a8c0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2a8d0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2a8e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2a8f0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2a900 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2a910 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2a920 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2a930 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a  n {F16400}.**.**
2a940 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a950 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2a960 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2a970 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2a980 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2a990 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2a9a0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2a9b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2a9c0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2a9d0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2a9e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2a9f0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2aa00 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2aa10 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2aa20 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2aa30 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
2aa40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2aa50 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2aa60 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
2aa70 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
2aa80 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
2aa90 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2aaa0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2aab0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2aac0 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
2aad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2aae0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2aaf0 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
2ab00 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
2ab10 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2ab20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ab30 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2ab40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2ab50 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2ab60 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2ab70 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2ab80 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2ab90 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2aba0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2abb0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2abc0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2abd0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2abe0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2abf0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2ac00 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71  eter. .** The sq
2ac10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2ac20 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63 65  oblob() inerface
2ac30 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2ac40 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2ac50 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ac60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2ac70 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2ac80 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2ac90 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2aca0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2acb0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2acc0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2acd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2ace0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2acf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2ad00 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2ad10 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2ad20 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2ad30 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2ad40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ad50 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2ad60 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2ad70 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2ad80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ad90 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2ada0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2adb0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2adc0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2add0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2ade0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2adf0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
2ae00 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2ae10 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2ae20 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2ae30 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2ae40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ae50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2ae60 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2ae70 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2ae80 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2ae90 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
2aea0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2aeb0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2aec0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2aed0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2aee0 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
2aef0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2af00 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2af10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2af20 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
2af30 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
2af40 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
2af50 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2af60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2af70 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2af80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2af90 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2afa0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2afb0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2afc0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2afd0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2afe0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2aff0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2b000 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2b010 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2b020 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2b030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2b040 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2b050 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2b060 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2b070 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2b080 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2b090 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2b0a0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2b0b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b0c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2b0d0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2b0e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b0f0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2b100 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
2b110 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
2b120 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2b130 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2b140 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2b150 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2b160 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2b170 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2b180 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2b190 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2b1a0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2b1b0 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
2b1c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2b1d0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2b1e0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2b1f0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2b200 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2b210 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2b220 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2b230 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
2b240 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
2b250 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
2b260 52 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  R. .**.** The sq
2b270 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2b280 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2b290 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a  causes SQLite.**
2b2a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2b2b0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
2b2c0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2b2d0 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a  LOB is to long.*
2b2e0 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 20  * to represent. 
2b2f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b300 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
2b310 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 73 20  rface.** causes 
2b320 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2b330 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 64  an exception ind
2b340 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
2b350 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
2b360 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
2b370 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b380 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
2b390 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2b3a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2b3b0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2b3c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2b3d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2b3e0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
2b3f0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2b400 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2b410 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
2b420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b430 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
2b440 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2b450 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2b460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b470 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b480 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
2b490 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2b4a0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2b4b0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2b4c0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
2b4d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
2b4e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2b4f0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2b500 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2b510 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b520 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b530 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
2b540 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b550 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
2b560 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 20  esult_text16(), 
2b570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2b580 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
2b590 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2b5a0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
2b5b0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
2b5c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2b5d0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2b5e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b5f0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
2b600 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
2b610 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
2b620 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
2b630 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2b640 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
2b650 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
2b660 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
2b670 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2b680 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
2b690 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
2b6a0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
2b6b0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
2b6c0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2b6d0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
2b6e0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2b6f0 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
2b700 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2b710 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2b720 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2b730 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
2b740 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
2b750 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
2b760 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
2b770 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20  d parameter .** 
2b780 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2b790 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2b7a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
2b7b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2b7c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b7d0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2b7e0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
2b7f0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
2b800 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
2b810 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
2b820 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
2b830 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
2b840 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
2b850 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
2b860 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
2b870 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
2b880 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
2b890 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2b8a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b8b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2b8c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b8d0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
2b8e0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
2b8f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
2b900 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
2b910 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
2b920 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
2b930 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74  t or blob result
2b940 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2b950 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2b960 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
2b970 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2b980 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2b990 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2b9a0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2b9b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b9c0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2b9d0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2b9e0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
2b9f0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 75 6d  .** SQLite assum
2ba00 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
2ba10 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20   or blob result 
2ba20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  is constant spac
2ba30 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f  e and.** does no
2ba40 74 20 63 6f 70 79 20 74 68 65 20 73 70 61 63 65  t copy the space
2ba50 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
2ba60 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
2ba70 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2ba80 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2ba90 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
2baa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bab0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2bac0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2bad0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2bae0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2baf0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2bb00 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2bb10 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2bb20 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2bb30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2bb40 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2bb50 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2bb60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2bb70 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2bb80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
2bb90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2bba0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
2bbb0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
2bbc0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2bbd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2bbe0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
2bbf0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
2bc00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bc10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
2bc20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
2bc30 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
2bc40 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
2bc50 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2bc60 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
2bc70 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
2bc80 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
2bc90 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 76 61  that [sqlite3_va
2bca0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2bcb0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2bcc0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2bcd0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2bce0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2bcf0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2bd00 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2bd10 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74  m..** A [protect
2bd20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bd30 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2bd40 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2bd50 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2bd60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bd70 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2bd80 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2bd90 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2bda0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2bdb0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2bdc0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2bdd0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2bde0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2bdf0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2be00 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2be10 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74 68 61  t thread .** tha
2be20 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2be30 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2be40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2be50 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 69 65  ction that recie
2be60 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2be70 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2be80 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2be90 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2bea0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2beb0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 33  S:.**.** {F16403
2bec0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65  } The default re
2bed0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2bee0 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  any SQL function
2bef0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
2bf00 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71  {F16406} The [sq
2bf10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2bf20 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  b(C,V,N,D)] inte
2bf30 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2bf40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2bf50 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2bf60 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2bf70 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20 4e 20   blob that is N 
2bf80 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
2bf90 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20    in length and 
2bfa0 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69  with content poi
2bfb0 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a  nted to by V..**
2bfc0 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54 68 65  .** {F16409} The
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2bfe0 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e  _double(C,V)] in
2bff0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c010 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2c020 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c030 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c040 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  int value V..**.
2c050 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68 65 20  ** {F16412} The 
2c060 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c070 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e  error(C,V,N)] in
2c080 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c090 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2c0a0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2c0b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c0c0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
2c0d0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
2c0e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2c0f0 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
2c100 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67  TF8 error messag
2c110 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20  e copied from V 
2c120 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  up to the.**    
2c130 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f        first zero
2c140 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e   byte or until N
2c150 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
2c160 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
2c170 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d  ..**.** {F16415}
2c180 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2c190 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56  sult_error16(C,V
2c1a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2c1b0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
2c1c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
2c1d0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c1e0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2c1f0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2c200 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
2c210 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c220 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61 74 69  and a UTF16 nati
2c230 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
2c240 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
2c250 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
2c260 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
2c270 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2c280 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
2c290 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
2c2a0 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
2c2b0 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
2c2c0 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54 68 65  .** {F16418} The
2c2d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c2e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
2c2f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2c300 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
2c310 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
2c320 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2c330 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
2c340 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
2c350 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
2c360 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
2c370 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
2c380 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
2c390 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32  ge..**.** {F1642
2c3a0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2c3b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2c3c0 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
2c3d0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c3e0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c3f0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
2c400 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2c410 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2c420 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
2c430 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
2c440 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
2c450 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
2c460 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essage..**.** {F
2c470 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
2c480 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c490 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
2c4a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c4b0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2c4c0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
2c4d0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
2c4e0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c4f0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
2c500 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
2c510 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2c520 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
2c530 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32  ed..**.** {F1642
2c540 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2c550 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
2c560 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c570 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c580 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c590 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c5a0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
2c5b0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
2c5c0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54  **.** {F16430} T
2c5d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c5e0 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
2c5f0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c600 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c610 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2c620 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2c630 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
2c640 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
2c650 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54 68 65  .** {F16433} The
2c660 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c670 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
2c680 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2c690 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2c6a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2c6b0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
2c6c0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36  L..**.** {F16436
2c6d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c6e0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
2c6f0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
2c700 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2c710 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2c720 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c730 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 38  C to be the UTF8
2c740 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
2c750 20 20 20 20 56 20 75 70 20 74 68 72 6f 75 67 68      V up through
2c760 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c770 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2c780 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a   are read if N.*
2c790 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f  *          is po
2c7a0 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2c7b0 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69  16439} The [sqli
2c7c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2c7d0 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  6(C,V,N,D)] inte
2c7e0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c7f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2c800 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2c810 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2c820 68 65 20 55 54 46 31 36 20 6e 61 74 69 76 65 20  he UTF16 native 
2c830 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
2c840 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 20 56         string  V
2c850 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2c860 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75 6e  first zero or un
2c870 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
2c880 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20 20  read if N.**    
2c890 20 20 20 20 20 20 69 73 20 70 6f 73 69 74 69 76        is positiv
2c8a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 32  e..**.** {F16442
2c8b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c8c0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
2c8d0 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
2c8e0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2c8f0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2c900 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2c910 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2c920 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  UTF16 big-endian
2c930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2c940 69 6e 67 20 20 56 20 75 70 20 74 68 72 6f 75 67  ing  V up throug
2c950 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2c960 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2c970 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a  s are read if N.
2c980 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
2c990 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2c9a0 46 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c  F16445} The [sql
2c9b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2c9c0 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
2c9d0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c9e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c9f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2ca00 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2ca10 65 20 74 68 65 20 55 54 46 31 36 20 6c 69 74 74  e the UTF16 litt
2ca20 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2ca30 20 20 20 20 20 20 73 74 72 69 6e 67 20 20 56 20        string  V 
2ca40 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2ca50 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75 6e 74  irst zero or unt
2ca60 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
2ca70 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20 20 20  ead if N.**     
2ca80 20 20 20 20 20 69 73 20 70 6f 73 69 74 69 76 65       is positive
2ca90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d  ..**.** {F16448}
2caa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2cab0 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d  sult_value(C,V)]
2cac0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2cad0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2cae0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2caf0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2cb00 20 62 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   be [unprotected
2cb10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2cb20 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
2cb30 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ct V..**.** {F16
2cb40 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
2cb50 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2cb60 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
2cb70 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2cb80 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cb90 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2cba0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
2cbb0 62 79 74 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c  byte blob of all
2cbc0 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   zeros..**.** {F
2cbd0 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
2cbe0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cbf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2cc00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2cc10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2cc20 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
2cc30 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
2cc40 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
2cc50 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
2cc60 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
2cc70 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37  g..**.** {F16457
2cc80 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
2cc90 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
2cca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2ccb0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2ccc0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2ccd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cce0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
2ccf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cd00 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
2cd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2cd20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cd30 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
2cd40 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2cd50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cd60 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2cd70 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
2cd80 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
2cd90 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
2cda0 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
2cdb0 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
2cdc0 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
2cdd0 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
2cde0 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
2cdf0 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
2ce00 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  able..**.** {F16
2ce10 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
2ce20 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2ce30 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2ce40 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(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 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2ce80 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2ce90 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2cea0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2ceb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cec0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2ced0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2cee0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2cef0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2cf00 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
2cf10 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
2cf20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
2cf30 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
2cf40 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
2cf50 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2cf60 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
2cf70 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
2cf80 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
2cf90 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68  * {F16463} If th
2cfa0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
2cfb0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2cfc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2cfd0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2cfe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2cff0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2d000 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
2d010 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
2d020 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
2d030 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2d040 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
2d050 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
2d060 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d070 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2d080 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
2d090 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
2d0a0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
2d0b0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
2d0c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
2d0d0 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
2d0e0 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20  IENT] then .**  
2d0f0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77          SQLite w
2d100 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2d110 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
2d120 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61   V as its only a
2d130 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  rgument.**      
2d140 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20      when it has 
2d150 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
2d160 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f  e V value..*/.vo
2d170 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d180 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2d190 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2d1a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2d1b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2d1c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d1d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2d1e0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2d1f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d200 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2d210 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d220 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2d230 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d240 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2d250 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2d260 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2d270 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d280 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2d290 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2d2a0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2d2b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2d2c0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2d2d0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2d2e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d2f0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2d300 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2d310 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d320 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2d330 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2d340 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d350 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2d360 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2d370 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2d380 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d390 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2d3a0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2d3b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d3c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d3d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2d3e0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2d3f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2d400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d410 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d420 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2d430 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2d440 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2d450 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d460 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2d470 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2d480 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2d490 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2d4a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d4b0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2d4c0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d4d0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2d4e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d4f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2d500 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2d510 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2d520 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2d530 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2d540 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2d550 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2d560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2d570 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2d580 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46 31 36  g Sequences {F16
2d590 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  600}.**.** These
2d5a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
2d5b0 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
2d5c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2d5d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71  es to the.** [sq
2d5e0 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73  lite3*] handle s
2d5f0 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
2d600 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
2d610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
2d620 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
2d630 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2d640 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
2d650 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2d660 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2d670 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2d680 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2d690 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2d6a0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2d6b0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
2d6c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d6d0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
2d6e0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
2d6f0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
2d700 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2d710 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2d720 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
2d730 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
2d740 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
2d750 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
2d760 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
2d770 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
2d780 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
2d790 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
2d7a0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
2d7b0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2d7c0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
2d7d0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2d7e0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
2d7f0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
2d800 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72  little-endian or
2d810 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
2d820 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2d830 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
2d840 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
2d850 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
2d860 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
2d870 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
2d880 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
2d890 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2d8a0 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
2d8b0 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
2d8c0 66 20 55 54 46 31 36 20 69 6e 20 74 68 65 20 6e  f UTF16 in the n
2d8d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2d8e0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d   of the host com
2d8f0 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  puter..**.** A p
2d900 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
2d910 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
2d920 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
2d930 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
2d940 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
2d950 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
2d960 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
2d970 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2d980 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2d990 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
2d9a0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
2d9b0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
2d9c0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
2d9d0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70  plication.** sup
2d9e0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
2d9f0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
2da00 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
2da10 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
2da20 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75  ed as.** the fou
2da30 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
2da40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2da50 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a  ollation() or.**
2da60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2da70 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73  collation16() as
2da80 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2da90 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
2daa0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
2dab0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
2dac0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
2dad0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
2dae0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
2daf0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2db00 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
2db10 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
2db20 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
2db30 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
2db40 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
2db50 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
2db60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
2db70 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
2db80 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
2db90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2dba0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2dbb0 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  n routine should
2dbc0 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74  .** return negat
2dbd0 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
2dbe0 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20  itive if.** the 
2dbf0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2dc00 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
2dc10 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2dc20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a  than the second.
2dc30 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  ** string. i.e. 
2dc40 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
2dc50 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
2dc60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2dc70 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
2dc80 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
2dc90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2dca0 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61  ().** excapt tha
2dcb0 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
2dcc0 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
2dcd0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
2dce0 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
2dcf0 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
2dd00 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2dd10 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
2dd20 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
2dd30 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
2dd40 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
2dd50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2dd60 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
2dd70 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
2dd80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dd90 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
2dda0 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
2ddb0 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68  royed when.** th
2ddc0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
2ddd0 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
2dde0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
2ddf0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
2de00 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  ions.** or when 
2de10 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
2de20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
2de30 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
2de40 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2de50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2de60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  TS:.**.** {F1660
2de70 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
2de80 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20  call to the.**  
2de90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2dea0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2deb0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2dec0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
2ded0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2dee0 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73  rs function F as
2def0 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
2df00 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f  function used to
2df10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70  .**          imp
2df20 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e  lement collation
2df30 20 58 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20   X on [database 
2df40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f  connection] B fo
2df50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  r.**          da
2df60 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65  tabases having e
2df70 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a  ncoding E..**.**
2df80 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69 74 65   {F16604} SQLite
2df90 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65   understands the
2dfa0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a   X parameter to.
2dfb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2dfc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2dfd0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2dfe0 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f  ,F,D)] as a zero
2dff0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
2e000 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
2e010 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61  ring in which ca
2e020 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f  se is ignored fo
2e030 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  r ASCII characte
2e040 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  rs and.**       
2e050 20 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e     is significan
2e060 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20  t for non-ASCII 
2e070 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2e080 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63 63 65  * {F16606} Succe
2e090 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b  ssive calls to [
2e0a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e0b0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2e0c0 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
2e0d0 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73        with the s
2e0e0 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42  ame values for B
2e0f0 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72  , X, and E, over
2e100 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65  ride prior value
2e110 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2e120 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a   P, F, and D..**
2e130 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54 68 65  .** {F16609} The
2e140 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
2e150 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e160 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e170 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
2e180 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
2e190 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
2e1a0 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
2e1b0 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
2e1c0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
2e1d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2e1e0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
2e1f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  te..**.** {F1661
2e200 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
2e210 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2e220 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
2e230 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
2e240 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {F16615} A colla
2e250 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2e260 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
2e270 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e280 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2e290 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
2e2a0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
2e2b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ()]..**.** {F166
2e2c0 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
2e2d0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
2e2e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e2f0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
2e300 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
2e310 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
2e320 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2e330 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
2e340 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
2e350 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
2e360 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
2e370 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2e380 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31  F..**.** {F16621
2e390 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
2e3a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e3b0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
2e3c0 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
2e3d0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
2e3e0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
2e3f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e400 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
2e410 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2e420 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
2e430 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
2e440 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
2e450 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {F16624} Follow
2e460 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
2e470 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e480 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2e490 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
2e4a0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
2e4b0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
2e4c0 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
2e4d0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
2e4e0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
2e4f0 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ns on [database 
2e500 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e  connection] B on
2e510 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61   text values tha
2e520 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  t.**          us
2e530 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  e the collating 
2e540 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e  sequence name X.
2e550 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20  .**.** {F16627} 
2e560 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2e570 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2e580 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
2e590 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
2e5a0 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
2e5b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e5c0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
2e5d0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
2e5e0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
2e5f0 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
2e600 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
2e610 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
2e620 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
2e630 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
2e640 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
2e650 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
2e660 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
2e670 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
2e680 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
2e690 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2e6a0 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
2e6b0 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
2e6c0 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
2e6d0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
2e6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
2e6f0 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
2e700 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
2e710 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
2e720 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
2e730 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
2e740 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
2e750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2e760 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2e770 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e780 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2e790 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2e7a0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2e7b0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2e7c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2e7d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2e7e0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2e7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e800 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2e810 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2e820 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2e830 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2e840 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2e850 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2e860 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2e870 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
2e880 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2e890 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
2e8a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e8b0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2e8c0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2e8d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2e8e0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2e8f0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2e900 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2e910 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2e920 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2e930 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2e940 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
2e950 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
2e960 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16700}.**.** T
2e970 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
2e980 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
2e990 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e9a0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
2e9b0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
2e9c0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
2e9d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2e9e0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
2e9f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61  d with the.** da
2ea00 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
2ea10 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
2ea20 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
2ea30 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2ea40 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72  nce is.** requir
2ea50 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
2ea60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
2ea70 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
2ea80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
2ea90 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
2eaa0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2eab0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
2eac0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
2ead0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2eae0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
2eaf0 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
2eb00 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71  . {F16703} If sq
2eb10 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2eb20 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
2eb30 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a  ed, the names.**
2eb40 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
2eb50 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
2eb60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2eb70 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  er. A call to ei
2eb80 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ther.** function
2eb90 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
2eba0 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
2ebb0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
2ebc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2ebd0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
2ebe0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
2ebf0 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
2ec00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2ec10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
2ec20 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2ec30 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2ec40 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2ec50 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
2ec60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2ec70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e   database.** han
2ec80 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  dle.  The third 
2ec90 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2eca0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
2ecb0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
2ecc0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2ecd0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
2ece0 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a  cating the most.
2ecf0 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  ** desirable for
2ed00 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
2ed10 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  on sequence func
2ed20 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a  tion required..*
2ed30 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
2ed40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2ed50 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2ed60 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2ed70 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
2ed80 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
2ed90 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
2eda0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
2edb0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
2edc0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
2edd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2ede0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2edf0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2ee00 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2ee10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ee20 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
2ee30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2ee40 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73 75 63  * {F16702} A suc
2ee50 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2ee60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2ee70 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
2ee80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2ee90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2eea0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
2eeb0 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
2eec0 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
2eed0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2eee0 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
2eef0 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
2ef00 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
2ef10 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
2ef20 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
2ef30 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2ef40 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
2ef50 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
2ef60 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
2ef70 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
2ef80 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  bout..**.** {F16
2ef90 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
2efa0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2efb0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2efc0 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
2efd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2efe0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2eff0 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
2f000 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
2f010 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
2f020 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
2f030 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f040 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
2f050 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
2f060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2f070 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  erface..**.** {F
2f080 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
2f090 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
2f0a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2f0b0 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
2f0c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
2f0d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2f0e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2f0f0 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
2f100 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
2f110 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
2f120 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2f130 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f140 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
2f150 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
2f160 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2f170 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
2f180 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
2f190 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
2f1a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2f1b0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2f1c0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a  6()]..**.** .*/.
2f1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2f1e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
2f1f0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2f200 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
2f210 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2f220 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2f230 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
2f240 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f250 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
2f260 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2f270 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2f280 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2f290 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
2f2a0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
2f2b0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2f2c0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2f2d0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2f2e0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2f2f0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2f300 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2f310 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2f320 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2f330 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2f340 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2f350 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2f360 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2f370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f380 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2f390 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2f3a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f3b0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2f3c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2f3d0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2f3e0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2f3f0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2f400 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2f410 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2f420 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2f430 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2f440 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2f450 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2f460 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2f470 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2f480 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2f490 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2f4a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2f4b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2f4c0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2f4d0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2f4e0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2f4f0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2f500 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2f510 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f530 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2f540 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2f550 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2f560 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2f570 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2f580 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2f590 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20  I3REF:  Suspend 
2f5a0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2f5b0 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35  Short Time {F105
2f5c0 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  30}.**.** The sq
2f5d0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
2f5e0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73  nction.** causes
2f5f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2f600 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2f610 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2f620 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2f630 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2f640 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2f650 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2f660 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
2f670 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
2f680 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
2f690 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
2f6a0 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
2f6b0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2f6c0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2f6d0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2f6e0 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
2f6f0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
2f700 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2f710 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2f720 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72  p actually .** r
2f730 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2f740 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2f750 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2f760 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
2f770 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2f780 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2f790 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2f7a0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2f7b0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2f7c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
2f7d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2f7e0 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54  **.** {F10533} T
2f7f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
2f800 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
2f810 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
2f820 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
2f830 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2f840 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2f850 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
2f860 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
2f870 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2f880 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
2f890 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
2f8a0 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
2f8b0 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
2f8c0 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54  **.** {F10536} T
2f8d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
2f8e0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
2f8f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2f900 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
2f910 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
2f920 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2f930 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
2f940 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
2f950 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
2f960 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
2f970 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
2f980 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
2f990 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
2f9a0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2f9b0 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66  PI3REF:  Name Of
2f9c0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
2f9d0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
2f9e0 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a  les {F10310}.**.
2f9f0 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
2fa00 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
2fa10 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
2fa20 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2fa30 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2fa40 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20  a folder (a.ka. 
2fa50 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2fa60 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2fa70 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2fa80 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
2fa90 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2faa0 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
2fab0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2fac0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2fad0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
2fae0 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
2faf0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
2fb00 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
2fb10 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
2fb20 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
2fb30 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20   to modify this 
2fb40 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20  variable once a 
2fb50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fb60 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  ion.** has been 
2fb70 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69  opened.  It is i
2fb80 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2fb90 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2fba0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2fbb0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2fbc0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2fbd0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2fbe0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2fbf0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2fc00 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69  n call and remai
2fc10 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72  n unchanged ther
2fc20 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  eafter..*/.SQLIT
2fc30 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
2fc40 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
2fc50 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
2fc60 50 49 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f  PI3REF:  Test To
2fc70 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74 61   See If The Data
2fc80 62 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d  base Is In Auto-
2fc90 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32  Commit Mode {F12
2fca0 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  930}.**.** The s
2fcb0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2fcc0 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
2fcd0 65 73 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  es returns non-z
2fce0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2fcf0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2fd00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fd10 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2fd20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2fd30 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2fd40 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .   Autocommit m
2fd50 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20  ode is on.** by 
2fd60 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f  default.  Autoco
2fd70 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2fd80 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2fd90 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2fda0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
2fdb0 20 69 73 20 72 65 65 6e 61 62 6c 65 64 20 62 79   is reenabled by
2fdc0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
2fdd0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
2fde0 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
2fdf0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
2fe00 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
2fe10 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
2fe20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
2fe30 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72  nsactions (error
2fe40 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
2fe50 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
2fe60 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b  TE_IOERR], .** [
2fe70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
2fe80 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
2fe90 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
2fea0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
2feb0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
2fec0 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
2fed0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
2fee0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
2fef0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69  to.** find out i
2ff00 66 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  f SQLite automat
2ff10 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2ff20 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2ff30 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2ff40 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2ff50 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2ff60 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2ff70 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54  **.** {F12931} T
2ff80 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
2ff90 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
2ffa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ffb0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
2ffc0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
2ffd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ffe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
2fff0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
30000 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
30010 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
30020 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tively..**.** {F
30030 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
30040 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
30050 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
30060 46 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  F12933} Autocomm
30070 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
30080 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
30090 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
300a0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ement..**.** {F1
300b0 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
300c0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
300d0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
300e0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
300f0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
30100 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
30110 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  * .**.** LIMITAT
30120 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31  IONS:.***.** {U1
30130 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72  2936} If another
30140 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
30150 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
30160 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
30170 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
30180 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69    connection whi
30190 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
301a0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
301b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
301c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  e.**          is
301d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
301e0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
301f0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
30200 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
30210 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20  3REF:  Find The 
30220 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
30230 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
30240 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d  atement {F13120}
30250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30260 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
30270 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
30280 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  s the [sqlite3*]
30290 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
302a0 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b   to which a.** [
302b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
302c0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
302d0 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  The database han
302e0 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  dle returned by 
302f0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
30300 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65  e.** is the same
30310 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
30320 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65   that was.** the
30330 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
30340 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
30350 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30360 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
30370 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
30380 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  o create the sta
30390 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
303a0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  rst place..**.**
303b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
303c0 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 68 65 20  ** {F13123} The 
303d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  [sqlite3_db_hand
303e0 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  le(S)] interface
303f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30400 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
30410 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
30420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
30430 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
30440 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
30450 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
30460 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
30470 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
30480 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a  lite3_stmt*);...
30490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
304a0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
304b0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
304c0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
304d0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
304e0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
304f0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
30500 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
30510 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
30520 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
30530 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
30540 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
30550 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
30560 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
30570 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
30580 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
30590 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
305a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
305b0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
305c0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
305d0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
305e0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
305f0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
30600 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
30610 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
30620 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
30630 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
30640 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
30650 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
30660 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
30670 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
30680 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
30690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
306a0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
306b0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
306c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
306d0 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74  sed through.** t
306e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  o the callback. 
306f0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
30700 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
30710 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72  k function .** r
30720 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
30730 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
30740 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
30750 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
30760 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
30770 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
30780 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
30790 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20  ed, its.** pArg 
307a0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
307b0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
307c0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
307d0 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
307e0 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
307f0 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
30800 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46  allback..**.** F
30810 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
30820 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
30830 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
30840 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20  id to have been 
30850 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
30860 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
30870 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
30880 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
30890 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
308a0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
308b0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
308c0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
308d0 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
308e0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
308f0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
30900 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
30910 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
30920 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
30930 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
30940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
30950 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
30960 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
30970 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
30980 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
30990 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
309a0 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
309b0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
309c0 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
309d0 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
309e0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
309f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30a00 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
30a10 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
30a20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
30a30 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
30a40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
30a50 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
30a60 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
30a70 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
30a80 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
30a90 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
30aa0 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
30ab0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
30ac0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
30ad0 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
30ae0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
30af0 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  mmits on [databa
30b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
30b10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d  ..**.** {F12952}
30b20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
30b30 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
30b40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
30b50 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
30b60 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
30b70 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
30b80 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
30b90 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame .**         
30ba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30bb0 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e  ction ] D , or N
30bc0 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
30bd0 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
30be0 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
30bf0 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ar [database con
30c00 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
30c10 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20  * {F12953} Each 
30c20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30c30 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
30c40 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
30c50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
30c60 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
30c70 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
30c80 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66  *.** {F12954} If
30c90 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
30ca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
30cb0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
30cc0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
30cd0 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d      then the com
30ce0 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
30cf0 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61  k is cancelled a
30d00 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
30d10 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
30d20 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
30d30 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
30d40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d  ..**.** {F12955}
30d50 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63   If the commit c
30d60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
30d70 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68  non-zero then th
30d80 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20  e commit is.**  
30d90 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65          converte
30da0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
30db0 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31  k..**.** {F12961
30dc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30dd0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
30de0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
30df0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
30e00 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
30e10 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
30e20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
30e30 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
30e40 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
30e50 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
30e60 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74  lls back on [dat
30e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30e80 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
30e90 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  62} The [sqlite3
30ea0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
30eb0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
30ec0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
30ed0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
30ee0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
30ef0 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
30f00 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20  the same .**    
30f10 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
30f20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c  connection ] D ,
30f30 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20   or NULL on the 
30f40 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20  first call.**   
30f50 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72         for a par
30f60 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73  ticular [databas
30f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
30f80 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20  .**.** {F12963} 
30f90 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
30fa0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30fb0 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65  ook()] overwrite
30fc0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
30fd0 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
30fe0 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63  tered by prior c
30ff0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  alls..**.** {F12
31000 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72  964} If the F ar
31010 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
31020 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
31030 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c  (D,F,P)] is NULL
31040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
31050 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68  n the rollback h
31060 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
31070 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f  cancelled and no
31080 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
31090 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
310a0 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
310b0 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a  ion rolls back..
310c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
310d0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
310e0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
310f0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
31100 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
31110 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
31120 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
31130 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
31140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
31150 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
31160 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
31170 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12970}.**.** 
31180 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
31190 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
311a0 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ace.** registers
311b0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
311c0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64 61  tion with the da
311d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
311e0 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  n identified by 
311f0 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61 72  the .** first ar
31200 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e 76  gument to be inv
31210 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
31220 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
31230 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
31240 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
31250 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
31260 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
31270 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  his function for
31280 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61   the same .** da
31290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
312a0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
312b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
312c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
312d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
312e0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
312f0 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77  e when a .** row
31300 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
31310 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
31320 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  . .** The first 
31330 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
31340 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61  callback is.** a
31350 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
31360 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
31370 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31380 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  ok()..** The sec
31390 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ond callback .**
313a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
313b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
313c0 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
313d0 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
313e0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65  UPDATE],.** depe
313f0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
31400 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
31410 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
31420 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
31430 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
31440 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d  .** fourth argum
31450 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
31460 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
31470 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64 61 74  nters to the dat
31480 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61  abase and .** ta
31490 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
314a0 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
314b0 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e   row..** The fin
314c0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
314d0 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65  meter is .** the
314e0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
314f0 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73  w..** In the cas
31500 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
31510 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
31520 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20  d after .** the 
31530 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
31540 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
31550 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
31560 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
31570 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
31580 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
31590 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
315a0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
315b0 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
315c0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
315d0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
315e0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
315f0 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
31600 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
31610 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
31620 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
31630 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
31640 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d  :.**.** {F12971}
31650 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   The [sqlite3_up
31660 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
31670 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ] interface caus
31680 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  es callback.**  
31690 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
316a0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
316b0 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61   with first para
316c0 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72  meter P whenever
316d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
316e0 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69  able row is modi
316f0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20  fied, inserted, 
31700 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a  or deleted on.**
31710 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
31720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31730 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 33  D..**.** {F12973
31740 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
31750 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
31760 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
31770 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
31780 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 20  *          of P 
31790 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73  for the previous
317a0 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d   call on the sam
317b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
317c0 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20  ection] D,.**   
317d0 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66         or NULL f
317e0 6f 72 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  or the first cal
317f0 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 35  l..**.** {F12975
31800 7d 20 49 66 20 74 68 65 20 75 70 64 61 74 65 20  } If the update 
31810 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20  hook callback F 
31820 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  in [sqlite3_upda
31830 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a  te_hook(D,F,P)].
31840 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 4e  **          is N
31850 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20  ULL then the no 
31860 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73  update callbacks
31870 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a   are made..**.**
31880 20 7b 46 31 32 39 37 37 7d 20 45 61 63 68 20 63   {F12977} Each c
31890 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
318a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
318b0 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72  P)] overrides pr
318c0 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20  ior calls.**    
318d0 20 20 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d        to the sam
318e0 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74  e interface on t
318f0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
31900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
31910 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20  .**.** {F12979} 
31920 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
31930 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
31940 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
31950 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20  ernal system.** 
31960 20 20 20 20 20 20 20 20 20 74 61 62 6c 65 73 20           tables 
31970 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d  such as sqlite_m
31980 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
31990 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f  _sequence are mo
319a0 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  dified..**.** {F
319b0 31 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e  12981} The secon
319c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
319d0 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  he update callba
319e0 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ck .**          
319f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
31a00 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
31a10 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53  TE_DELETE] or [S
31a20 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a  QLITE_UPDATE],.*
31a30 2a 20 20 20 20 20 20 20 20 20 20 64 65 70 65 6e  *          depen
31a40 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
31a50 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
31a60 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
31a70 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
31a80 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65  .** {F12983} The
31a90 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
31aa0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
31ab0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
31ac0 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20  ain pointers.** 
31ad0 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f           to zero
31ae0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
31af0 38 20 73 74 72 69 6e 67 73 20 77 68 69 63 68 20  8 strings which 
31b00 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  are the names of
31b10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31b20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
31b30 62 6c 65 20 74 68 61 74 20 69 73 20 62 65 69 6e  ble that is bein
31b40 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b  g updated...** {
31b50 46 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61  F12985} The fina
31b60 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
31b70 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69  eter is the rowi
31b80 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74  d of the row aft
31b90 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
31ba0 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73  he change occurs
31bb0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31bc0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
31bd0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
31be0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
31bf0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
31c00 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
31c10 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
31c20 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
31c30 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65  API3REF:  Enable
31c40 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
31c50 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b  ed Pager Cache {
31c60 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10330}.**.** Th
31c70 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
31c80 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
31c90 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
31ca0 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
31cb0 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
31cc0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
31cd0 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f  etween connectio
31ce0 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ns to the same d
31cf0 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72  atabase..** Shar
31d00 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
31d10 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
31d20 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61 62  s true and disab
31d30 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
31d40 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e  ent.** is false.
31d50 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61  .**.** Cache sha
31d60 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
31d70 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20  and disabled.** 
31d80 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
31d90 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69  ocess. {END} Thi
31da0 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
31db0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
31dc0 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20  on 3.5.0..** In 
31dd0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f  prior versions o
31de0 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e  f SQLite, sharin
31df0 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  g was.** enabled
31e00 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72   or disabled for
31e10 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70   each thread sep
31e20 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  arately..**.** T
31e30 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
31e40 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
31e50 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
31e60 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
31e70 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
31e80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
31e90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
31ea0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
31eb0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
31ec0 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
31ed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
31ee0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
31ef0 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
31f00 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
31f10 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
31f20 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
31f30 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
31f40 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20  ables cannot be 
31f50 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72  used with a shar
31f60 65 64 20 63 61 63 68 65 2e 20 20 20 57 68 65 6e  ed cache.   When
31f70 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
31f80 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65   is enabled, the
31f90 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31fa0 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75  _module()] API u
31fb0 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a  sed to register.
31fc0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
31fd0 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  s will always re
31fe0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  turn an error..*
31ff0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32000 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
32010 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
32020 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61  cache was.** ena
32030 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
32040 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
32050 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a  An [error code].
32060 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  ** is returned o
32070 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
32080 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
32090 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
320a0 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
320b0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
320c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
320d0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
320e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
320f0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
32100 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
32110 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
32120 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
32130 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32140 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20 41 20   .** {F10331} A 
32150 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
32160 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
32170 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
32180 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20  cache(B)].**    
32190 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c        will enabl
321a0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68 61  e or disable sha
321b0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 66  red cache mode f
321c0 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  or any subsequen
321d0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
321e0 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73  created [databas
321f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
32200 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
32210 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 36  s..**.** {F10336
32220 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 63 61  } When shared ca
32230 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
32240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
32250 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a  ate_module()].**
32260 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
32270 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ace will always 
32280 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
32290 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20  .**.** {F10337} 
322a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
322b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
322c0 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (B)] interface r
322d0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
322e0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69     [SQLITE_OK] i
322f0 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
32300 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
32310 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
32320 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  lly..**.** {F103
32330 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68 65  39} Shared cache
32340 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
32350 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20  default..*/.int 
32360 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
32370 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29  hared_cache(int)
32380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32390 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46  F:  Attempt To F
323a0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20  ree Heap Memory 
323b0 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17340}.**.** T
323c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
323d0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
323e0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
323f0 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65  o.** free N byte
32400 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
32410 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
32420 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
32430 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
32440 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65  ions held by the
32450 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72   database labrar
32460 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
32470 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68   used.** to cach
32480 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  e database pages
32490 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
324a0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
324b0 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d  ample of.** non-
324c0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
324d0 2e 20 20 53 71 6c 69 74 65 33 5f 72 65 6c 65 61  .  Sqlite3_relea
324e0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
324f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
32500 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
32510 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68  lly freed, which
32520 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
32530 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74  r less.** than t
32540 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
32550 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ted..**.** INVAR
32560 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
32570 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  7341} The [sqlit
32580 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32590 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  y(N)] interface 
325a0 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20  attempts to.**  
325b0 20 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62          free N b
325c0 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d  ytes of heap mem
325d0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
325e0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
325f0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  l.**          me
32600 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
32610 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
32620 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e 0a 2a  abase labrary..*
32630 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54 68  *.** {F16342} Th
32640 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  e [sqlite3_relea
32650 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65  se_memory(N)] re
32660 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
32680 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
32690 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68  reed, which migh
326a0 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
326b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
326c0 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
326d0 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20  quested..*/.int 
326e0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
326f0 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a  memory(int);../*
32700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49  .** CAPI3REF:  I
32710 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
32720 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37 33   Heap Size {F173
32730 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
32740 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
32750 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
32760 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73  e.** places a "s
32770 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68  oft" limit on th
32780 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
32790 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
327a0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
327b0 20 62 79 20 53 51 4c 69 74 65 2e 20 49 66 20 61   by SQLite. If a
327c0 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63  n internal alloc
327d0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
327e0 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c  ed .** that woul
327f0 64 20 65 78 63 65 65 64 20 74 68 65 20 73 6f 66  d exceed the sof
32800 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
32810 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
32820 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69  emory()] is.** i
32830 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  nvoked one or mo
32840 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
32850 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
32860 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
32870 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e  tion.** is made.
32880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74  .**.** The limit
32890 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74   is called "soft
328a0 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a 2a 2a  ", because if.**
328b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
328c0 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e  e_memory()] cann
328d0 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69  ot.** free suffi
328e0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
328f0 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
32900 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
32910 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
32920 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
32930 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
32940 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
32950 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
32960 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72  ** A negative or
32970 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
32980 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
32990 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
329a0 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
329b0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
329c0 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
329d0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
329e0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
329f0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20  hausted..** The 
32a00 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
32a10 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
32a20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a  limit is zero..*
32a30 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
32a40 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20  s a best effort 
32a50 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66  to honor the sof
32a60 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a  t heap limit.  .
32a70 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
32a80 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
32a90 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c 20 65 78  nnot honored, ex
32aa0 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
32ab0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
32ac0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
32ad0 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73  cation.  This is
32ae0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
32af0 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22  s .** called a "
32b00 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74  soft" limit.  It
32b10 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
32b20 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  y..**.** Prior t
32b30 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
32b40 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75   3.5.0, this rou
32b50 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72  tine only constr
32b60 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79  ained the memory
32b70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  .** allocated by
32b80 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
32b90 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65   - the same thre
32ba0 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73  ad in which this
32bb0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73   routine.** runs
32bc0 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  .  Beginning wit
32bd0 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
32be0 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74   3.5.0, the soft
32bf0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a   heap limit is.*
32c00 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c  * applied to all
32c10 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61   threads. The va
32c20 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f  lue specified fo
32c30 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
32c40 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75  limit.** is an u
32c50 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
32c60 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61  e total memory a
32c70 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c  llocation for al
32c80 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a  l threads. In.**
32c90 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
32ca0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
32cb0 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
32cc0 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
32cd0 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
32ce0 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  al threads..**.*
32cf0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32d00 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65  .** {F16351} The
32d10 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
32d20 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e  eap_limit(N)] in
32d30 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
32d40 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20   soft limit.**  
32d50 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74          of N byt
32d60 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  es on the amount
32d70 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
32d80 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
32d90 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  cated.**        
32da0 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33    using [sqlite3
32db0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
32dc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
32dd0 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a  ] at any point.*
32de0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69  *          in ti
32df0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  me..**.** {F1635
32e00 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  2} If a call to 
32e10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
32e20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
32e30 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a  ealloc()] would.
32e40 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73  **          caus
32e50 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75  e the total amou
32e60 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20  nt of allocated 
32e70 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64  memory to exceed
32e80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32e90 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32ea0 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
32eb0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
32ec0 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
32ed0 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61           in an a
32ee0 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65  ttempt to reduce
32ef0 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67   the memory usag
32f00 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65  e prior to proce
32f10 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  eding.**        
32f20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72    with the memor
32f30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74  y allocation att
32f40 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  empt..**.** {F16
32f50 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  353} Calls to [s
32f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
32f70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
32f80 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69  lloc()] that tri
32f90 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  gger.**         
32fa0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64   attempts to red
32fb0 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  uce memory usage
32fc0 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66   through the sof
32fd0 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20  t heap limit.** 
32fe0 20 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69           mechani
32ff0 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e  sm continue even
33000 20 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20   if the attempt 
33010 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79  to reduce memory
33020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61  .**          usa
33030 67 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66  ge is unsuccessf
33040 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ul..**.** {F1635
33050 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72  4} A negative or
33060 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
33070 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  N in a call to.*
33080 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33090 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
330a0 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68  mit(N)] means th
330b0 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
330c0 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  oft.**          
330d0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b  heap limit and [
330e0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
330f0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
33100 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  nly be.**       
33110 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d     called when m
33120 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74  emory is complet
33130 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a  ely exhausted..*
33140 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68  *.** {F16355} Th
33150 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
33160 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
33170 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
33180 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20  .**.** {F16358} 
33190 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
331a0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
331b0 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69  limit(N)] overri
331c0 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  des the.**      
331d0 20 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62      values set b
331e0 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c  y all prior call
331f0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
33200 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
33210 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  it(int);../*.** 
33220 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61  CAPI3REF:  Extra
33230 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
33240 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
33250 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a  Table {F12850}.*
33260 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33270 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74  e.** returns met
33280 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  a-data about a s
33290 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
332a0 66 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  f a specific dat
332b0 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61  abase.** table a
332c0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
332d0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  the connection h
332e0 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20  andle passed as 
332f0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
33300 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  on .** argument.
33310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d  .**.** The colum
33320 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
33330 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
33340 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
33350 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a  parameters to .*
33360 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
33370 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
33380 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
33390 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
333a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
333b0 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
333c0 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
333d0 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
333e0 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
333f0 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
33400 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55  ULL. If it is NU
33410 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
33420 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
33430 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
33440 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
33450 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
33460 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61  orithm as the da
33470 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73  tabase engine us
33480 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76  es to .** resolv
33490 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
334a0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
334b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
334c0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
334d0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
334e0 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
334f0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
33500 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
33510 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
33520 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
33530 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
33540 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61  arameters .** ma
33550 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
33560 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f   Meta informatio
33570 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  n is returned by
33580 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
33590 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
335a0 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
335b0 65 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71  e 5th and subseq
335c0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
335d0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
335e0 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a  . Any of these .
335f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  ** arguments may
33600 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69   be NULL, in whi
33610 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
33620 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
33630 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e  t of meta .** in
33640 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d  formation is omm
33650 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72  itted..**.** <pr
33660 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20  e>.** Parameter 
33670 20 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20      Output Type 
33680 20 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e       Description
33690 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  .** ------------
336a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
336b0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20  -------.**.**   
336c0 35 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73  5th         cons
336d0 74 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74  t char*      Dat
336e0 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20  a type.**   6th 
336f0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
33700 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66  ar*      Name of
33710 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c   the default col
33720 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
33730 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20  .**   7th       
33740 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
33750 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
33760 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
33770 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
33780 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20  **   8th        
33790 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
337a0 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
337b0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
337c0 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
337d0 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20  **   9th        
337e0 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
337f0 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
33800 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52  lumn is AUTOINCR
33810 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  EMENT.** </pre>.
33820 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  **.**.** The mem
33830 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
33840 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
33850 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33860 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65  d for the .** de
33870 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
33880 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
33890 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
338a0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
338b0 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  xt .** call to a
338c0 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75  ny sqlite API fu
338d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
338e0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
338f0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
33900 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e   a view, then an
33910 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
33920 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
33930 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
33940 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
33950 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
33960 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45   and an .** INTE
33970 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
33980 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
33990 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
339a0 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
339b0 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74  tput .** paramet
339c0 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
339d0 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
339e0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
339f0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
33a00 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
33a10 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e  lared IPK column
33a20 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
33a30 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  t parameters are
33a40 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c   set as .** foll
33a50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
33a60 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
33a70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
33a80 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
33a90 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
33aa0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
33ab0 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
33ac0 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
33ad0 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
33ae0 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a   0.** </pre>.**.
33af0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
33b00 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
33b10 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
33b20 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
33b30 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
33b40 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
33b50 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
33b60 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
33b70 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
33b80 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
33b90 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20  ound, an SQLITE 
33ba0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
33bb0 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
33bc0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c  ror message.** l
33bd0 65 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62  eft in the datab
33be0 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62  ase handle (to b
33bf0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
33c00 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
33c10 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ())..**.** This 
33c20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
33c30 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
33c40 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
33c50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
33c60 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
33c70 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
33c80 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
33c90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
33ca0 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
33cb0 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
33cc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
33cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33ce0 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
33cf0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
33d00 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
33d10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
33d20 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
33d30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
33d40 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
33d50 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
33d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
33d70 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
33d80 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
33d90 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
33da0 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
33db0 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
33dc0 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
33dd0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
33de0 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
33df0 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
33e00 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
33e10 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
33e20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
33e30 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
33e40 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
33e50 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
33e60 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
33e70 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
33e80 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
33e90 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
33ea0 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
33eb0 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
33ec0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
33ed0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
33ee0 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
33ef0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
33f00 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
33f10 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30  xtension {F12600
33f20 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d  }.**.** {F12601}
33f30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
33f40 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
33f50 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d  terface.** attem
33f60 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53  pts to load an S
33f70 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
33f80 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
33f90 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a  d in the file.**
33fa0 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30 32 7d   zFile. {F12602}
33fb0 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   The entry point
33fc0 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31 32 36   is zProc. {F126
33fd0 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65  03} zProc may be
33fe0 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68 20 63   0.** in which c
33ff0 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
34000 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
34010 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f 20 22  defaults.** to "
34020 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f  sqlite3_extensio
34030 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b  n_init"..**.** {
34040 46 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69  F12604} The sqli
34050 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
34060 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  on() interface s
34070 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  hall.** return [
34080 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
34090 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54  ccess and [SQLIT
340a0 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65  E_ERROR] if some
340b0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
340c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 35 7d  ..**.** {F12605}
340d0 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20  .** If an error 
340e0 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
340f0 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
34100 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  en the.** sqlite
34110 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
34120 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  () interface sha
34130 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20 66 69  ll attempt to fi
34140 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
34150 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73  h .** error mess
34160 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
34170 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
34180 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
34190 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b  _malloc()]..** {
341a0 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e  END}  The callin
341b0 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
341c0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
341d0 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67  ry.** by calling
341e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
341f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 36  ]..**.** {F12606
34200 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c  }.** Extension l
34210 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
34220 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
34230 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
34240 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
34250 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
34260 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 61  ng this API or a
34270 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
34280 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
34290 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
342a0 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
342b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
342c0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
342d0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
342e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
342f0 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
34300 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
34310 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
34320 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
34330 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
34340 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
34350 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
34360 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
34370 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
34380 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
34390 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
343a0 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
343b0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
343c0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
343d0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
343e0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
343f0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
34400 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F12620}.**.** 
34410 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65  So as not to ope
34420 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73  n security holes
34430 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63   in older applic
34440 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a  ations that are.
34450 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f  ** unprepared to
34460 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e   deal with exten
34470 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e  sion loading, an
34480 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20  d as a means of 
34490 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74  disabling.** ext
344a0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77  ension loading w
344b0 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
344c0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
344d0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  , the following.
344e0 2a 2a 20 41 50 49 20 69 73 20 70 72 6f 76 69 64  ** API is provid
344f0 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b  ed to turn the [
34500 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
34510 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e  ension()] mechan
34520 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66  ism on and.** of
34530 66 2e 20 20 7b 46 31 32 36 32 32 7d 20 49 74 20  f.  {F12622} It 
34540 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c  is off by defaul
34550 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74 69 63  t. {END} See tic
34560 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a  ket #1863..**.**
34570 20 7b 46 31 32 36 32 31 7d 20 43 61 6c 6c 20 74   {F12621} Call t
34580 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
34590 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
345a0 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69  () routine.** wi
345b0 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74  th onoff==1 to t
345c0 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
345d0 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20  ading on.** and 
345e0 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
345f0 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74  ff==0 to turn it
34600 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
34610 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71   {END}.*/.int sq
34620 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
34630 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
34640 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
34650 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
34660 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e  3REF: Make Arran
34670 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d  gements To Autom
34680 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e  atically Load An
34690 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36   Extension {F126
346a0 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  40}.**.** {F1264
346b0 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  1} This function
346c0 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 6e  .** registers an
346d0 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
346e0 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 20 61   point that is a
346f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
34700 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72  oked.** whenever
34710 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
34720 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
34730 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ened using.** [s
34740 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
34750 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
34760 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
34770 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b 45 4e 44  open_v2()]. {END
34780 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  }.**.** This API
34790 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20   can be invoked 
347a0 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74  at program start
347b0 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  up in order to r
347c0 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  egister.** one o
347d0 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c  r more staticall
347e0 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69  y linked extensi
347f0 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  ons that will be
34800 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f   available.** to
34810 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73   all new databas
34820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  e connections..*
34830 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d 20 44 75  *.** {F12642} Du
34840 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f  plicate extensio
34850 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20  ns are detected 
34860 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  so calling this 
34870 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65  routine multiple
34880 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
34890 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f  he same extensio
348a0 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a  n is harmless..*
348b0 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d 20 54 68  *.** {F12643} Th
348c0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
348d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
348e0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
348f0 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74  an array.** that
34900 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
34910 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28  m sqlite_malloc(
34920 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79 6f 75 20  ). {END} If you 
34930 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
34940 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20  k.** checker on 
34950 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
34960 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
34970 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
34980 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65  is.** array, the
34990 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  n invoke [sqlite
349a0 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
349b0 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a  ension()] prior.
349c0 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74  ** to shutdown t
349d0 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72  o free the memor
349e0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 34  y..**.** {F12644
349f0 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65  } Automatic exte
34a00 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
34a10 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
34a20 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
34a30 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
34a40 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
34a50 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
34a60 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
34a70 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
34a80 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
34a90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34aa0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
34ab0 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74  oid *xEntryPoint
34ac0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
34ad0 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d  REF: Reset Autom
34ae0 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c  atic Extension L
34af0 6f 61 64 69 6e 67 20 7b 46 31 32 36 36 30 7d 0a  oading {F12660}.
34b00 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d 20 54  **.** {F12661} T
34b10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
34b20 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
34b30 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
34b40 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ** automatic ext
34b50 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20  ensions. {END}  
34b60 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  This.** routine 
34b70 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
34b80 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b  t of all prior [
34b90 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
34ba0 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c  ension()].** cal
34bb0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36  ls..**.** {F1266
34bc0 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73  2} This call dis
34bd0 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20  abled automatic 
34be0 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c  extensions in al
34bf0 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d  l threads. {END}
34c00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
34c10 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
34c20 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
34c30 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
34c40 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
34c50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
34c60 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
34c70 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  id sqlite3_reset
34c80 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34c90 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a  void);.../*.****
34ca0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
34cb0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
34cc0 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
34cd0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
34ce0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
34cf0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
34d00 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
34d10 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
34d20 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
34d30 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
34d40 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
34d50 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
34d60 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
34d70 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
34d80 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
34d90 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
34da0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
34db0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
34dc0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
34dd0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
34de0 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20  nism stablizes, 
34df0 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
34e00 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
34e10 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
34e20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
34e30 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
34e40 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
34e50 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
34e60 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
34e70 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
34e80 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
34e90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
34ea0 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
34eb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
34ec0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
34ed0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
34ee0 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
34ef0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
34f00 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
34f10 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
34f20 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
34f30 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
34f40 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
34f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
34f60 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
34f70 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a 20 4b 45  t {F18000}.** KE
34f80 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
34f90 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20 41 20 6d  module.**.** A m
34fa0 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73  odule is a class
34fb0 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c   of virtual tabl
34fc0 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  es.  Each module
34fd0 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62   is defined.** b
34fe0 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  y an instance of
34ff0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
35000 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20  tructure.  This 
35010 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
35020 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20  ts.** mostly of 
35030 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
35040 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63  module..*/.struc
35050 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
35060 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
35070 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
35080 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
35090 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
350a0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
350b0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
350c0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
350d0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
350e0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
350f0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
35100 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
35110 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
35120 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35130 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
35140 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
35150 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
35160 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
35170 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
35180 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
35190 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
351a0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
351b0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
351c0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
351d0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
351e0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
351f0 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
35200 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35210 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
35220 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
35230 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
35240 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
35250 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
35260 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
35270 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
35280 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
35290 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
352a0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
352b0 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
352c0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
352d0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
352e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
352f0 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
35300 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
35310 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
35320 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
35330 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35340 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
35350 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
35360 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
35370 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
35380 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
35390 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
353a0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
353b0 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
353c0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
353d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
353e0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
353f0 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
35400 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
35410 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
35420 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35430 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
35440 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
35450 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
35460 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
35470 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
35480 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
35490 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
354a0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
354b0 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
354c0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
354d0 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
354e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
354f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35500 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
35510 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35520 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35530 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
35540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35550 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
35560 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61  ;..  int (*xRena
35570 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  me)(sqlite3_vtab
35580 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63   *pVtab, const c
35590 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a  har *zNew);.};..
355a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
355b0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
355c0 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69  dexing Informati
355d0 6f 6e 20 7b 46 31 38 31 30 30 7d 0a 2a 2a 20 4b  on {F18100}.** K
355e0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
355f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a  _index_info.**.*
35600 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
35610 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
35620 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
35630 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
35640 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
35650 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
35660 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
35670 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73  ly from the xBes
35680 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64  tIndex.** method
35690 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d   of an sqlite3_m
356a0 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c  odule.  The fiel
356b0 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
356c0 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
356d0 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
356e0 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
356f0 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
35700 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
35710 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
35720 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
35730 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ields..**.** The
35740 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
35750 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
35760 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
35770 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20  aints of the.** 
35780 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20  form:.**.**     
35790 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78      column OP ex
357a0 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f  pr.**.** Where O
357b0 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
357c0 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
357d0 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61  t;=.  .** The pa
357e0 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
357f0 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  r is stored.** i
35800 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
35810 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f  op.  The index o
35820 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
35830 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43  stored in .** aC
35840 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
35850 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e  umn.  aConstrain
35860 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
35870 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
35880 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
35890 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
358a0 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
358b0 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
358c0 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
358d0 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
358e0 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54   cannot..**.** T
358f0 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
35900 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
35910 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
35920 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
35930 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
35940 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
35950 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
35960 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
35970 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
35980 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
35990 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
359a0 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
359b0 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
359c0 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43  sible..** The aC
359d0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
359e0 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
359f0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
35a00 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74  s in the correct
35a10 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65  .** form that re
35a20 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69  fer to the parti
35a30 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
35a40 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65  ble being querie
35a50 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61  d..**.** Informa
35a60 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
35a70 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
35a80 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
35a90 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20  erBy[]..** Each 
35aa0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
35ab0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
35ac0 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
35ad0 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
35ae0 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
35af0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
35b00 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
35b10 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
35b20 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
35b30 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
35b40 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
35b50 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30    If argvIndex>0
35b60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
35b70 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
35b80 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
35b90 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
35ba0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
35bb0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
35bc0 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
35bd0 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20  ry in argv.  If 
35be0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
35bf0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
35c00 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
35c10 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
35c20 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
35c30 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
35c40 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
35c50 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
35c60 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
35c70 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78  e..**.** The idx
35c80 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
35c90 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
35ca0 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
35cb0 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73  to xFilter..** s
35cc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
35cd0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
35ce0 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72  xPtr if needToFr
35cf0 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
35d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
35d10 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
35d20 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
35d30 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  om xFilter will 
35d40 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
35d50 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
35d60 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
35d70 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
35d80 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
35d90 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
35da0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
35db0 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
35dc0 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
35dd0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
35de0 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
35df0 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
35e00 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
35e10 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
35e20 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
35e30 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
35e40 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
35e50 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
35e60 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
35e70 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
35e80 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
35e90 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
35ea0 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
35eb0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
35ec0 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
35ed0 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72  */.  int nConstr
35ee0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
35ef0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
35f00 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
35f10 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  int */.  struct 
35f20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
35f30 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20  nstraint {.     
35f40 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
35f50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
35f60 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64  umn on left-hand
35f70 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61   side of constra
35f80 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  int */.     unsi
35f90 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20  gned char op;   
35fa0 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61        /* Constra
35fb0 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a  int operator */.
35fc0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
35fd0 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f  ar usable;     /
35fe0 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63  * True if this c
35ff0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61  onstraint is usa
36000 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20  ble */.     int 
36010 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20  iTermOffset;    
36020 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
36030 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74  ternally - xBest
36040 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e  Index should ign
36050 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  ore */.  } *aCon
36060 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
36070 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20      /* Table of 
36080 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
36090 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e  straints */.  in
360a0 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
360b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
360c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74  er of terms in t
360d0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
360e0 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  se */.  struct s
360f0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
36100 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20  erby {.     int 
36110 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
36120 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
36130 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75  number */.     u
36140 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73  nsigned char des
36150 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  c;       /* True
36160 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73   for DESC.  Fals
36170 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20  e for ASC. */.  
36180 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20  } *aOrderBy;    
36190 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68             /* Th
361a0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
361b0 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75  e */..  /* Outpu
361c0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
361d0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
361e0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
361f0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
36200 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
36210 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
36220 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
36230 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
36240 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
36250 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
36260 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
36270 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
36280 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
36290 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
362a0 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
362b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
362c0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
362d0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
362e0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
362f0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
36300 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
36310 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
36320 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
36330 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
36340 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
36350 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
36360 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
36370 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
36380 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
36390 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
363a0 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
363b0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
363c0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
363d0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
363e0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
363f0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
36400 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
36410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36420 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
36430 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
36440 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
36450 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
36460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36470 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
36480 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
36490 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
364a0 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
364b0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
364c0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
364d0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
364e0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
364f0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
36500 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
36510 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
36520 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
36530 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31  plementation {F1
36540 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  8200}.**.** This
36550 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64   routine is used
36560 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
36570 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77  ew module name w
36580 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a  ith an SQLite.**
36590 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f   connection.  Mo
365a0 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20  dule names must 
365b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65  be registered be
365c0 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65  fore creating ne
365d0 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  w.** virtual tab
365e0 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c  les on the modul
365f0 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69  e, or before usi
36600 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20 76  ng preexisting v
36610 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73  irtual.** tables
36620 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a   of the module..
36630 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
36640 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20  reate_module(.  
36650 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36660 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
36670 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
36680 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
36690 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
366a0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
366b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
366c0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
366d0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
366e0 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
366f0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
36700 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
36710 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  d *             
36720 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
36730 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
36740 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29  te/xConnect */.)
36750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36760 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
36770 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
36780 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32  ementation {F182
36790 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
367a0 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69  outine is identi
367b0 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69 74  cal to the sqlit
367c0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
367d0 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  () method above,
367e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
367f0 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
36800 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
36810 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
36820 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
36830 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
36840 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
36850 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
36860 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74  bles API..*/.int
36870 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36880 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
36890 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
368a0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
368b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
368c0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
368d0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
368e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
368f0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
36900 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
36910 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
36920 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
36930 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
36940 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
36950 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36960 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
36970 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
36980 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
36990 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
369a0 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
369b0 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
369c0 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
369d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
369e0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74  rtual Table Inst
369f0 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 46 31 38  ance Object {F18
36a00 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  010}.** KEYWORDS
36a10 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
36a20 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c  *.** Every modul
36a30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36a40 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
36a50 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
36a60 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74  g structure.** t
36a70 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
36a80 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
36a90 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
36aa0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
36ab0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
36ac0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
36ad0 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
36ae0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
36af0 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20  ation.   The.** 
36b00 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20  purpose of this 
36b10 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f  superclass is to
36b20 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20   define certain 
36b30 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20  fields that are 
36b40 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c  common.** to all
36b50 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
36b60 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56  tations..**.** V
36b70 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
36b80 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
36b90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
36ba0 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
36bb0 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
36bc0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
36bd0 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d  rintf() to zErrM
36be0 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
36bf0 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
36c00 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
36c10 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
36c20 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
36c30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a  sqlite3_free().*
36c40 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
36c50 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
36c60 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41  g to zErrMsg.  A
36c70 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
36c80 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
36c90 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
36ca0 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
36cb0 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
36cc0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
36cd0 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
36ce0 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
36cf0 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
36d00 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
36d10 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20  eroed.  Note.** 
36d20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72  that sqlite3_mpr
36d30 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
36d40 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73  e3_free() are us
36d50 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73  ed on the zErrMs
36d60 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65  g field.** since
36d70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
36d80 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70  are commonly imp
36d90 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64  lemented in load
36da0 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  able extensions 
36db0 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20  which.** do not 
36dc0 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73  have access to s
36dd0 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20  qlite3MPrintf() 
36de0 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29  or sqlite3Free()
36df0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
36e00 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
36e10 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
36e20 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
36e30 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
36e40 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
36e50 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
36e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e70 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
36e80 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63  nternally */.  c
36e90 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
36ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36eb0 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
36ec0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
36ed0 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
36ee0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
36ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
36f00 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
36f10 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
36f20 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
36f30 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36f40 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
36f50 6a 65 63 74 20 20 7b 46 31 38 30 32 30 7d 0a 2a  ject  {F18020}.*
36f60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
36f70 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a  te3_vtab_cursor.
36f80 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75  **.** Every modu
36f90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
36fa0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
36fb0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  s of the followi
36fc0 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  ng structure.** 
36fd0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
36fe0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
36ff0 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20  nto the virtual 
37000 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73  table and are us
37010 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
37020 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
37030 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
37040 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
37050 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e  ing the.** xOpen
37060 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
37070 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64  odule.  Each mod
37080 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
37090 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a  on will define.*
370a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
370b0 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74   a cursor struct
370c0 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20  ure to suit its 
370d0 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  own needs..**.**
370e0 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   This superclass
370f0 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72   exists in order
37100 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64   to define field
37110 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20  s of the cursor 
37120 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d  that.** are comm
37130 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d  on to all implem
37140 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74  entations..*/.st
37150 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
37160 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c  b_cursor {.  sql
37170 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
37180 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61  ;      /* Virtua
37190 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20  l table of this 
371a0 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56  cursor */.  /* V
371b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
371c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
371d0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
371e0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
371f0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
37200 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
37210 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41   The Schema Of A
37220 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b   Virtual Table {
37230 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F18280}.**.** Th
37240 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43  e xCreate and xC
37250 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f  onnect methods o
37260 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74  f a module use t
37270 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
37280 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74  .** to declare t
37290 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e  he format (the n
372a0 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70  ames and datatyp
372b0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
372c0 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72  s) of.** the vir
372d0 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79  tual tables they
372e0 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69   implement..*/.i
372f0 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
37300 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
37310 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43  , const char *zC
37320 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a  reateTable);../*
37330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76  .** CAPI3REF: Ov
37340 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f  erload A Functio
37350 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20  n For A Virtual 
37360 54 61 62 6c 65 20 7b 46 31 38 33 30 30 7d 0a 2a  Table {F18300}.*
37370 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
37380 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
37390 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
373a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
373b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
373c0 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74  g the xFindFunct
373d0 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74  ion method.  But
373e0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
373f0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
37400 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
37410 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
37420 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
37430 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
37440 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
37450 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
37460 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
37470 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
37480 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
37490 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
374a0 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
374b0 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
374c0 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
374d0 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
374e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
374f0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
37500 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
37510 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
37520 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
37530 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
37540 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
37550 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
37560 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
37570 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
37580 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
37590 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
375a0 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64   be a place-hold
375b0 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
375c0 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
375d0 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c  ed.** by virtual
375e0 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54   tables..**.** T
375f0 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62  his API should b
37600 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72  e considered par
37610 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
37620 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
37630 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78  ,.** which is ex
37640 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73  perimental and s
37650 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
37660 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37670 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
37680 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
37690 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
376a0 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
376b0 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
376c0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
376d0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
376e0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
376f0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
37700 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
37710 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
37720 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
37730 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
37740 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
37750 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
37760 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
37770 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
37780 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
37790 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
377a0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
377b0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
377c0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
377d0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
377e0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
377f0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
37800 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
37810 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
37820 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
37830 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
37840 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
37850 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
37860 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
37870 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
37880 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
37890 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
378a0 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
378b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
378c0 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
378d0 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a   BLOB {F17800}.*
378e0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
378f0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
37900 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
37910 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
37920 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  .** incremental 
37930 49 2f 4f 20 63 61 6e 20 62 65 20 70 72 65 66 6f  I/O can be prefo
37940 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73  rmed..** Objects
37950 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
37960 65 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20  e created by.** 
37970 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
37980 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72 6f  en()] and destro
37990 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
379a0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
379b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
379c0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
379d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
379e0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
379f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
37a00 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
37a10 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
37a20 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e  ons of the blob.
37a30 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
37a40 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
37a50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37a60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
37a70 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 65  .** blob in byte
37a80 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
37a90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
37aa0 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
37ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ac0 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
37ad0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
37ae0 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F17810}.**.** 
37af0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20  This interfaces 
37b00 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c 65 20 74  opens a handle t
37b10 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74  o the blob locat
37b20 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f  ed.** in row iRo
37b30 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  w,, column zColu
37b40 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
37b50 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
37b60 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
37b70 72 64 73 2c 20 20 74 68 65 20 73 61 6d 65 20 62  rds,  the same b
37b80 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 20 62  lob that would b
37b90 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
37ba0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
37bb0 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
37bc0 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
37bd0 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69   WHERE rowid = i
37be0 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b  Row;.** </pre> {
37bf0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  END}.**.** If th
37c00 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
37c10 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  r is non-zero, t
37c20 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
37c30 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61  d for .** read a
37c40 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
37c50 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20   If it is zero, 
37c60 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
37c70 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20  ed for read .** 
37c80 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  access..**.** On
37c90 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
37ca0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
37cb0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a  d and the new .*
37cc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
37cd0 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69  | blob handle] i
37ce0 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70  s written to *pp
37cf0 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74 68 65 72 77  Blob. .** Otherw
37d00 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  ise an error cod
37d10 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  e is returned an
37d20 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  d .** any value 
37d30 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c  written to *ppBl
37d40 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  ob should not be
37d50 20 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c   used by the cal
37d60 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ler..** This fun
37d70 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64  ction sets the d
37d80 61 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65  atabase-handle e
37d90 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
37da0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
37db0 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
37dc0 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
37dd0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
37de0 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52  )]..** .** INVAR
37df0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
37e00 37 38 31 33 7d 20 41 20 73 75 63 63 65 73 73 66  7813} A successf
37e10 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
37e20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
37e30 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c  ob_open(D,B,T,C,
37e40 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20  R,F,P)].**      
37e50 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 6f 70      interface op
37e60 65 6e 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ens an [sqlite3_
37e70 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 6f  blob] object P o
37e80 6e 20 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20  n the blob.**   
37e90 20 20 20 20 20 20 20 69 6e 20 63 6f 6c 75 6d 6e         in column
37ea0 20 43 20 6f 66 20 74 61 62 6c 65 20 54 20 69 6e   C of table T in
37eb0 20 64 61 74 61 62 61 73 65 20 42 20 6f 6e 20 5b   database B on [
37ec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37ed0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
37ee0 31 37 38 31 34 7d 20 41 20 73 75 63 63 65 73 73  17814} A success
37ef0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
37f00 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  f [sqlite3_blob_
37f10 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20 73 74 61  open(D,...)] sta
37f20 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rts.**          
37f30 61 20 6e 65 77 20 74 72 61 6e 73 61 63 74 69 6f  a new transactio
37f40 6e 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  n on [database c
37f50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20  onnection] D if 
37f60 74 68 61 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  that connection.
37f70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
37f80 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 61 20  ot already in a 
37f90 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a  transaction..**.
37fa0 2a 2a 20 7b 46 31 37 38 31 36 7d 20 54 68 65 20  ** {F17816} The 
37fb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
37fc0 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50  en(D,B,T,C,R,F,P
37fd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6f 70 65  )] interface ope
37fe0 6e 73 20 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20  ns the blob.**  
37ff0 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
38000 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73   and write acces
38010 73 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  s if and only if
38020 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72   the F parameter
38030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
38040 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  non-zero..**.** 
38050 7b 46 31 37 38 31 39 7d 20 54 68 65 20 5b 73 71  {F17819} The [sq
38060 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
38070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
38080 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
38090 20 6f 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   on .**         
380a0 20 73 75 63 63 65 73 73 20 61 6e 64 20 61 6e 20   success and an 
380b0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
380c0 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
380d0 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  ure..**.** {F178
380e0 32 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20  21} If an error 
380f0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76  occurs during ev
38100 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  aluation of [sql
38110 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44  ite3_blob_open(D
38120 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
38130 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 75 65     then subseque
38140 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
38150 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d  ite3_errcode(D)]
38160 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
38170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29  qlite3_errmsg(D)
38180 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
38190 65 72 72 6d 73 67 31 36 28 44 29 5d 20 77 69 6c  errmsg16(D)] wil
381a0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
381b0 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e       information
381c0 20 61 70 70 72 6f 70 72 61 74 65 20 66 6f 72 20   approprate for 
381d0 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69  that error..*/.i
381e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
381f0 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
38200 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
38210 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
38220 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
38230 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
38240 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
38250 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
38260 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
38270 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
38280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38290 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48    Close A BLOB H
382a0 61 6e 64 6c 65 20 7b 46 31 37 38 33 30 7d 0a 2a  andle {F17830}.*
382b0 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70  *.** Close an op
382c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  en [sqlite3_blob
382d0 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e   | blob handle].
382e0 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61  .**.** Closing a
382f0 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
38300 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
38310 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
38320 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
38330 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
38340 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
38350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
38360 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
38370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38380 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d  on is in autocom
38390 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20 49 66 20  mit mode..** If 
383a0 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20  any writes were 
383b0 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42  made to the BLOB
383c0 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20  , they might be 
383d0 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a  held in cache.**
383e0 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65   until the close
383f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68   operation if th
38400 65 79 20 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e  ey will fit. {EN
38410 44 7d 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68  D}.** Closing th
38420 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72  e BLOB often for
38430 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a  ces the changes.
38440 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61  ** out to disk a
38450 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f  nd so if any I/O
38460 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74   errors occur, t
38470 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  hey will likely 
38480 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20  occur.** at the 
38490 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c  time when the BL
384a0 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b  OB is closed.  {
384b0 46 31 37 38 33 33 7d 20 41 6e 79 20 65 72 72 6f  F17833} Any erro
384c0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75  rs that occur du
384d0 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20  ring.** closing 
384e0 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20  are reported as 
384f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72  a non-zero retur
38500 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  n value..**.** T
38510 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
38520 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c  d unconditionall
38530 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73  y.  Even if this
38540 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
38550 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  .** an error cod
38560 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73  e, the BLOB is s
38570 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  till closed..**.
38580 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
38590 2a 0a 2a 2a 20 7b 46 31 37 38 33 33 7d 20 54 68  *.** {F17833} Th
385a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
385b0 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65 72 66  close(P)] interf
385c0 61 63 65 20 63 6c 6f 73 65 73 20 61 6e 0a 2a 2a  ace closes an.**
385d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
385e0 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20  e3_blob] object 
385f0 50 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 70 65  P previously ope
38600 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ned using.**    
38610 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
38620 6c 6f 62 5f 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a  lob_open()]..**.
38630 2a 2a 20 7b 46 31 37 38 33 36 7d 20 43 6c 6f 73  ** {F17836} Clos
38640 69 6e 67 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ing an [sqlite3_
38650 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 75 73 69  blob] object usi
38660 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
38670 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
38680 73 65 28 29 5d 20 73 68 61 6c 6c 20 63 61 75 73  se()] shall caus
38690 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
386a0 61 6e 73 61 63 74 69 6f 6e 20 74 6f 0a 2a 2a 20  ansaction to.** 
386b0 20 20 20 20 20 20 20 20 20 63 6f 6d 6d 69 74 20           commit 
386c0 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
386d0 6f 74 68 65 72 20 6f 70 65 6e 20 5b 73 71 6c 69  other open [sqli
386e0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
386f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
38700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38710 6d 65 6e 74 73 5d 20 6f 6e 20 74 68 65 20 73 61  ments] on the sa
38720 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
38730 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 0a 2a 2a 20  nection] and.** 
38740 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
38750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38760 6e 5d 20 69 73 20 69 6e 0a 2a 2a 20 20 20 20 20  n] is in.**     
38770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 67 65       [sqlite3_ge
38780 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 20 7c 20 61  t_autocommit | a
38790 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
387a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20  .**.** {F17839} 
387b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
387c0 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65  b_close(P)] inte
387d0 72 66 61 63 65 73 20 63 6c 6f 73 65 73 20 74 68  rfaces closes th
387e0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
387f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
38800 6a 65 63 74 20 50 20 75 6e 63 6f 6e 64 69 74 69  ject P unconditi
38810 6f 6e 61 6c 6c 79 2c 20 65 76 65 6e 20 69 66 0a  onally, even if.
38820 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
38830 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
38840 50 29 5d 20 72 65 74 75 72 6e 73 20 73 6f 6d 65  P)] returns some
38850 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
38860 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
38870 20 20 20 20 20 20 20 20 20 20 0a 2a 2f 0a 69 6e            .*/.in
38880 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
38890 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
388a0 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
388b0 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54  I3REF:  Return T
388c0 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
388d0 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 34 30 7d  en BLOB {F17840}
388e0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
388f0 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
38900 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65  of the blob acce
38910 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f  ssible via the o
38920 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
38930 5f 62