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

Artifact 7f1438fb2bef8eb1fdd4f09b4e709a39d53e6963:


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 33 20 32 30 30 38 2f  in,v 1.293 2008/
05f0: 30 33 2f 31 39 20 31 34 3a 31 35 3a 33 35 20 64  03/19 14:15:35 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 43 6f 6d 70 69 6c  CAPI3REF: Compil
17580 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
17590 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a  ment {F13010}.**
175a0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
175b0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
175c0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
175d0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
175e0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
175f0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
17600 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20  these routines. 
17610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
17620 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69   argument "db" i
17630 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s an [database c
17640 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f  onnection] .** o
17650 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
17660 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
17670 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
17680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17690 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
176a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a  3_open16()]. .**
176b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
176c0 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74  ment "zSql" is t
176d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
176e0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
176f0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
17700 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
17710 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
17720 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
17730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17740 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
17750 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20   uses UTF-8 and 
17760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
17770 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
17780 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
17790 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45  * use UTF-16. {E
177a0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ND}.**.** If the
177b0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
177c0 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  is less.** than 
177d0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
177e0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
177f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
17800 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e  minator..** If n
17810 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
17820 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
17830 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
17840 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73  ber of .** bytes
17850 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
17860 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
17870 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
17880 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
17890 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
178a0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
178b0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
178c0 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e  racter or .** un
178d0 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74 68  til the nByte-th
178e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
178f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45   comes first. {E
17900 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69  ND}.**.** *pzTai
17910 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
17920 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
17930 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
17940 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  d of the.** firs
17950 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
17960 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
17970 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f  routines only co
17980 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74  mpiles the first
17990 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
179a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
179b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
179c0 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
179d0 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
179e0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
179f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
17a00 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
17a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
17a20 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
17a30 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
17a40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
17a50 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65  )].  Or if there
17a60 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
17a70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74 20  pStmt is.** set 
17a80 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
17a90 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
17aa0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
17ab0 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20  the input.** is 
17ac0 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67  and empty string
17ad0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
17ae0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
17af0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b  et to NULL..** {
17b00 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c  U13018} The call
17b10 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
17b20 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
17b30 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a   deleting the.**
17b40 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
17b50 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67  atement.** using
17b60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
17b70 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
17b80 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
17b90 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
17ba0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
17bb0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
17bc0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a   Otherwise an .*
17bd0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
17be0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
17c00 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
17c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17c20 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
17c30 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
17c40 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
17c50 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
17c60 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
17c70 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
17c80 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
17c90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
17ca0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
17cb0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
17cc0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
17cd0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
17ce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
17cf0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
17d00 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
17d10 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
17d20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
17d30 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
17d40 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45  nal SQL text. {E
17d50 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73 20  ND} This causes 
17d60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
17d70 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
17d80 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
17d90 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
17da0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
17db0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
17dc0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
17dd0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
17de0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
17df0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
17e00 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
17e10 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
17e20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
17e30 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
17e40 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
17e50 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
17e60 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
17e70 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
17e80 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
17e90 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
17ea0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
17eb0 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
17ec0 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
17ed0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
17ee0 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
17ef0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
17f00 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
17f10 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
17f20 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  r, .** [SQLITE_S
17f30 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20  CHEMA] is now a 
17f40 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
17f50 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  lling.** [sqlite
17f60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17f70 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
17f80 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
17f90 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
17fa0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
17fb0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
17fc0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
17fd0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
17fe0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
17ff0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
18000 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44  MA] return. {END
18010 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  }.** </li>.**.**
18020 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
18030 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
18040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
18050 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
18060 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
18070 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  led .** [error c
18080 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
18090 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
180a0 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20   .** The legacy 
180b0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
180c0 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t [sqlite3_step(
180d0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
180e0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a  turn a generic.*
180f0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
18100 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64   result code and
18110 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
18120 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
18130 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
18140 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
18150 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
18160 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
18170 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
18180 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  em..** With the 
18190 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74  "v2" prepare int
181a0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
181b0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
181c0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a  or the error is.
181d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  ** returned imme
181e0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
181f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
18200 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
18210 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20  ** {F13011} The 
18220 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18230 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
18240 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
18250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18260 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
18270 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
18280 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
18290 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
182a0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
182b0 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
182c0 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20  ** {F13012} The 
182d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
182e0 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
182f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18300 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18310 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
18320 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
18330 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
18340 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
18350 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
18360 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
18370 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
18380 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
18390 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68 65   {F13013} If the
183a0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
183b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
183c0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
183d0 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
183e0 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
183f0 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
18400 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
18410 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20  SQL text is.**  
18420 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f          read fro
18430 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  m zSql is read u
18440 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
18450 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
18460 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49  **.** {F13014} I
18470 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
18480 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
18490 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
184a0 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
184b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
184c0 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
184d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
184e0 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  en nBytes bytes.
184f0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
18500 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f  text is read fro
18510 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  m zSql..**.** {F
18520 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74  13015} In [sqlit
18530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
18540 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c  ,zSql,N,P,pzTail
18550 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
18560 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nts.**          
18570 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75  if the zSql inpu
18580 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
18590 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51  more than one SQ
185a0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  L statement.**  
185b0 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61          and pzTa
185c0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  il is not NULL, 
185d0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
185e0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
185f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
18600 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
18610 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
18620 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
18630 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20  ent in zSql..** 
18640 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57           <todo>W
18650 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c  hat does *pzTail
18660 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65   point to if the
18670 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d  re is one statem
18680 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  ent?</todo>.**.*
18690 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63  * {F13016} A suc
186a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
186b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
186c0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70  _v2(db,zSql,N,pp
186d0 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Stmt,...)].**   
186e0 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66         or one of
186f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72   its variants wr
18700 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d  ites into *ppStm
18710 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
18720 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
18730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
18740 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74  ment] or a point
18750 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20  er to NULL.**   
18760 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63         if zSql c
18770 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20  ontains nothing 
18780 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
18790 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74  space or comment
187a0 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  s. .**.** {F1301
187b0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
187c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
187d0 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
187e0 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
187f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
18800 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
18810 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
18820 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
18830 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ure..**.** {F130
18840 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69  21} Before [sqli
18850 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
18860 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74  Sql,nByte,ppStmt
18870 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73  ,pzTail)] or its
18880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72  .**          var
18890 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e  iants returns an
188a0 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75   error (any valu
188b0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
188c0 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20  LITE_OK]).**    
188d0 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20 73        it first s
188e0 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e  ets *ppStmt to N
188f0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
18900 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
18910 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
18920 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
18930 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
18940 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
18950 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
18960 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
18970 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
18980 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
18990 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
189a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
189b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
189c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
189d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
189e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
189f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
18a00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
18a10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
18a20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
18a30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
18a40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18a50 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
18a60 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
18a70 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
18a80 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
18a90 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
18aa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
18ab0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
18ac0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
18ad0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
18ae0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
18af0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
18b00 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
18b10 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
18b20 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
18b30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
18b40 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
18b50 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
18b60 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
18b70 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
18b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
18b90 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
18ba0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
18bb0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
18bc0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
18bd0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
18be0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
18bf0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
18c00 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
18c10 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
18c20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
18c30 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
18c40 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
18c50 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
18c60 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
18c70 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
18c80 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
18c90 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
18ca0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
18cb0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
18cc0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
18cd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
18ce0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
18cf0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
18d00 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
18d10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
18d20 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
18d30 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
18d40 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
18d50 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
18d60 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
18d70 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
18d80 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
18d90 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
18da0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
18db0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
18dc0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
18dd0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
18de0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
18df0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
18e00 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
18e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
18e20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
18e30 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
18e40 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
18e50 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20 75  ereface can be u
18e60 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
18e70 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
18e80 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
18e90 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
18ea0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
18eb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
18ec0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
18ed0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  :.**.** {F13101}
18ee0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
18ef0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
18f00 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
18f10 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
18f20 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
18f30 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
18f40 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
18f50 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
18f60 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
18f70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
18f80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18f90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
18fa0 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  2()],.**        
18fb0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
18fc0 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
18fd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
18fe0 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20  r to a.**       
18ff0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
19000 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
19010 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
19020 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
19030 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
19040 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
19050 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d  ..**.** {F13102}
19060 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
19070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
19080 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
19090 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
190a0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
190b0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
190c0 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
190d0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
190e0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
190f0 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
19100 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
19110 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
19120 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
19130 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
19140 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19150 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
19160 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d  ..**.** {F13103}
19170 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
19180 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
19190 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
191a0 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
191b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
191c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
191d0 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
191e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
191f0 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
19200 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
19210 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
19220 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
19230 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
19240 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
19250 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30  e Object  {F1500
19260 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
19270 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
19280 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
19290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
192a0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
192b0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
192c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
192d0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
192e0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
192f0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
19300 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
19310 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  le..** SQLite us
19320 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
19330 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
19340 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a   it stores.  .**
19350 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69   Values stored i
19360 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
19370 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a  objects can be.*
19380 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  * be integers, f
19390 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
193a0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
193b0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
193c0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
193d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
193e0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
193f0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
19400 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
19410 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
19420 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
19430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
19440 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
19450 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
19460 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
19470 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
19480 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
19490 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
194a0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
194b0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
194c0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
194d0 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68 65  ifies .** whethe
194e0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
194f0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
19500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
19510 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
19520 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
19530 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
19540 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
19550 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
19560 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
19570 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
19580 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
19590 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
195a0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
195b0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
195c0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
195d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
195e0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
195f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
19600 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
19610 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
19620 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  th SQLITE_THREAD
19630 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68 20  SAFE=0 and with 
19640 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
19650 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
19660 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72   0).** then ther
19670 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
19680 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70  ion between.** p
19690 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
196a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
196b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
196c0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a 2a  nd they can be.*
196d0 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  * used interchan
196e0 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c  gable.  However,
196f0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
19700 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
19710 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  .** is recommend
19720 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
19730 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64 69  ions make the di
19740 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
19750 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72 6f  n.** between pro
19760 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
19770 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
19780 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
19790 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72 65  n if.** they are
197a0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65 64   single threaded
197b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
197c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
197d0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
197e0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
197f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
19800 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 70  ementation of ap
19810 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
19820 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
19830 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
19840 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
19850 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
19860 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
19870 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
19880 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
19890 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
198a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
198b0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
198c0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
198d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
198e0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
198f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
19900 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65 72  e()].  All other
19910 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 74  .** interfaces t
19920 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 33 5f  hat use sqlite3_
19930 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 70 72  value require pr
19940 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
19950 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
19960 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
19970 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
19980 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
19990 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69  REF:  SQL Functi
199a0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
199b0 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a  t {F16001}.**.**
199c0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
199d0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
199e0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
199f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
19a00 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
19a10 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
19a20 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
19a30 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62  e3_context.** ob
19a40 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66  ject is always f
19a50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19a60 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  o application-de
19a70 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
19a80 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ons..*/.typedef 
19a90 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
19aa0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
19ab0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
19ac0 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e  API3REF:  Bindin
19ad0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
19ae0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
19af0 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49  {F13500}.**.** I
19b00 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
19b10 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
19b20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19b30 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72  ] and its.** var
19b40 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20  iants, literals 
19b50 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20 62  may be replace b
19b60 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e  y a parameter in
19b70 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65   one.** of these
19b80 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
19b90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
19ba0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
19bb0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
19bc0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
19bd0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
19be0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
19bf0 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
19c00 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
19c10 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
19c20 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d  l,.** VVV alpha-
19c30 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65  numeric paramete
19c40 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76  r name..** The v
19c50 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70  alues of these p
19c60 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
19c70 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
19c80 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a  ameter names".**
19c90 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
19ca0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
19cb0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
19cc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
19cd0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
19ce0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
19cf0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19d00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
19d10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
19d20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70  always.** is a p
19d30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
19d40 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
19d50 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
19d60 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
19d70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
19d80 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65  ts variants. The
19d90 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
19da0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
19db0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
19dc0 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65  r to be set. The
19dd0 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
19de0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
19df0 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
19e00 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70   same named.** p
19e10 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
19e20 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
19e30 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
19e40 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
19e50 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
19e60 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
19e70 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
19e80 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78  e. .** The index
19e90 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
19ea0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
19eb0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
19ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
19ed0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
19ee0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
19ef0 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
19f00 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
19f10 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
19f20 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
19f30 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
19f40 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
19f50 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  and the compile-
19f60 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  time.** paramete
19f70 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52  r SQLITE_MAX_VAR
19f80 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65  IABLE_NUMBER (de
19f90 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
19fa0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
19fb0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
19fc0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
19fd0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
19fe0 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
19ff0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
1a000 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
1a010 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
1a020 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
1a030 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69  er of bytes.** i
1a040 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
1a050 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
1a060 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  he value is the 
1a070 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
1a080 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65  es</u>.** in the
1a090 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
1a0a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1a0b0 74 65 72 73 2e 20 20 20 54 68 65 20 6e 75 6d 62  ters.   The numb
1a0c0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64  er.** of bytes d
1a0d0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1a0e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1a0f0 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f  tor at the end o
1a100 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  f strings..** If
1a110 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1a120 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
1a130 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
1a140 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
1a150 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
1a160 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
1a170 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1a180 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  r..**.** The fif
1a190 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1a1a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1a1b0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
1a1c0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
1a1d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1a1e0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
1a1f0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
1a200 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
1a210 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
1a220 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
1a230 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1a240 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  . If the fifth a
1a250 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
1a260 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1a270 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1a280 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
1a290 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
1a2a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1a2b0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
1a2c0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
1a2d0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1a2e0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20  be freed..** If 
1a2f0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1a300 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1a310 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1a320 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
1a330 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
1a340 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1a350 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
1a360 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
1a370 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
1a380 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
1a390 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
1a3a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
1a3b0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
1a3c0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
1a3d0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
1a3e0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
1a3f0 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f  h zeros.  A zero
1a400 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1a410 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1a420 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1a430 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1a440 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  t size) while it
1a450 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1a460 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1a470 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1a480 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1a490 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  -holders for BLO
1a4a0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1a4b0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1a4c0 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
1a4d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1a4e0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
1a4f0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1a500 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20  . A negative.** 
1a510 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1a520 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1a530 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1a540 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1a550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1a560 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1a570 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1a580 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1a590 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1a5a0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1a5b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1a5c0 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1a5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1a5e0 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1a5f0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1a600 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1a610 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1a620 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1a630 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1a640 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1a650 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a660 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1a670 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1a680 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1a690 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1a6a0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1a6b0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1a6c0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1a6d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1a6e0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1a6f0 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1a700 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1a710 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e  if malloc fails.
1a720 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1a730 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
1a740 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
1a750 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1a760 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
1a770 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
1a780 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
1a790 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
1a7a0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
1a7b0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
1a7c0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
1a7d0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
1a7e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
1a7f0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
1a800 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
1a810 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
1a820 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
1a830 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
1a840 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
1a850 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
1a860 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
1a870 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1a880 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
1a890 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
1a8a0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
1a8b0 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
1a8c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1a8d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1a8e0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1a8f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1a900 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1a910 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1a920 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1a930 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1a940 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1a950 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  506} The [sqlite
1a960 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20  3_prepare | SQL 
1a970 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1a980 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a  er] recognizes.*
1a990 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e  *          token
1a9a0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22  s of the forms "
1a9b0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
1a9c0 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
1a9d0 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20  "@VVV".**       
1a9e0 20 20 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65     as SQL parame
1a9f0 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20  ters, where NNN 
1aa00 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
1aa10 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  of one or more.*
1aa20 2a 20 20 20 20 20 20 20 20 20 20 64 69 67 69 74  *          digit
1aa30 73 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20  s and where VVV 
1aa40 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
1aa50 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a  of one or more .
1aa60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 70 68  **          alph
1aa70 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61 63 74  anumeric charact
1aa80 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69  ers or "::" opti
1aa90 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
1aaa0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  by.**          a
1aab0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1aac0 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64  ng no spaces and
1aad0 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1aae0 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a  n parentheses..*
1aaf0 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68  *.** {F13509} Th
1ab00 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20  e initial value 
1ab10 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
1ab20 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ter is NULL..**.
1ab30 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20  ** {F13512} The 
1ab40 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20  index of an "?" 
1ab50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1ab60 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e   one larger than
1ab70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ab80 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
1ab90 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
1aba0 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20  to the left, or 
1abb0 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  1 if.**         
1abc0 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20   the "?" is the 
1abd0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
1abe0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
1abf0 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78  13515} The index
1ac00 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51   of an "?NNN" SQ
1ac10 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  L parameter is t
1ac20 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a  he integer NNN..
1ac30 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54  **.** {F13518} T
1ac40 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
1ac50 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f  :VVV", "$VVV", o
1ac60 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72  r "@VVV" SQL par
1ac70 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
1ac80 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
1ac90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c  s the index of l
1aca0 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63  eftmost occuranc
1acb0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
1acc0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1acd0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
1ace0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
1acf0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
1ad00 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
1ad10 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1ad20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
1ad30 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1ad40 61 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ance.**         
1ad50 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
1ad60 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
1ad70 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
1ad80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1ad90 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b  * {F13521} The [
1ada0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1adb0 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
1adc0 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20 77  compiler] fail w
1add0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
1ade0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  an [SQLITE_RANGE
1adf0 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69  ] error if the i
1ae00 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1ae10 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
1ae20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61       is less tha
1ae30 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72 20 74  n 1 or greater t
1ae40 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  han SQLITE_MAX_V
1ae50 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a  ARIABLE_NUMBER..
1ae60 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
1ae70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ae80 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
1ae90 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
1aea0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1aeb0 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
1aec0 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
1aed0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1aee0 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
1aef0 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
1af00 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
1af10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
1af20 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
1af30 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1af40 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
1af50 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
1af60 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1af70 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
1af80 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
1af90 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
1afa0 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
1afb0 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
1afc0 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
1afd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
1afe0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
1aff0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1b000 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
1b010 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
1b020 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
1b030 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
1b040 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1b050 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
1b060 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
1b070 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1b080 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
1b090 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
1b0a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1b0b0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
1b0c0 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
1b0d0 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
1b0e0 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
1b0f0 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   of the blob or 
1b100 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
1b110 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
1b120 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
1b130 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
1b140 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
1b150 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1b160 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1b170 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
1b180 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1b190 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
1b1a0 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
1b1b0 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
1b1c0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
1b1d0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
1b1e0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
1b1f0 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
1b200 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
1b210 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
1b220 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1b230 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1b250 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1b260 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
1b270 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b280 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1b290 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
1b2a0 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
1b2b0 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
1b2c0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
1b2d0 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
1b2e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1b2f0 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
1b300 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
1b310 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
1b320 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
1b330 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
1b340 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
1b350 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
1b360 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
1b370 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
1b380 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1b390 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1b3a0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1b3b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1b3c0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1b3d0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1b3e0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1b3f0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1b400 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
1b410 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
1b420 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
1b430 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1b440 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
1b450 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20 20 20  kes a .**       
1b460 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
1b470 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66 6f 72  of V value befor
1b480 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
1b490 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e 20  .** {F13545} In 
1b4a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1b4b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1b4c0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1b4d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1b4e0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1b4f0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1b500 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1b510 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1b520 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
1b530 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
1b540 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
1b550 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
1b560 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
1b570 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
1b580 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 76 61  **          V va
1b590 6c 75 65 20 61 66 74 65 72 20 69 74 20 68 61 73  lue after it has
1b5a0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
1b5b0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a  the V value..**.
1b5c0 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e 20 63  ** {F13548} In c
1b5d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1b5e0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
1b5f0 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
1b600 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
1b610 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62 20 6f       is a blob o
1b620 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
1b630 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62  zero-length blob
1b640 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
1b650 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31  e..**.** {F13551
1b660 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1b670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1b680 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
1b690 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
1b6a0 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
1b6b0 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
1b6c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
1b6d0 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
1b6e0 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
1b6f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1b700 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
1b710 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1b720 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1b730 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1b740 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
1b750 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1b760 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
1b770 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
1b780 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
1b790 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1b7a0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
1b7b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
1b7c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1b7d0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
1b7e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
1b7f0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
1b800 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
1b810 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
1b820 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1b830 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
1b840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1b850 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1b860 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1b870 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1b880 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
1b890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1b8a0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
1b8b0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
1b8c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1b8d0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
1b8e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1b8f0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
1b900 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1b910 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1b920 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1b930 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
1b940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1b950 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
1b960 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30 30 7d  ameters {F13600}
1b970 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1b980 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
1b990 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
1b9a0 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  er of SQL parame
1b9b0 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65  ters.** in a pre
1b9c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
1b9d0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
1b9e0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
1b9f0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
1ba00 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
1ba10 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
1ba20 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
1ba30 2a 2a 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73  ** place-holders
1ba40 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1ba50 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1ba60 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1ba70 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1ba80 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1ba90 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
1baa0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
1bab0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
1bac0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
1bad0 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  est parameter..*
1bae0 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  * For all forms 
1baf0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1bb00 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1bb10 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  d to the number 
1bb20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72  of.** unique par
1bb30 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1bb40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1bb50 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68  NNN are used, th
1bb60 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61  ere may.** be ga
1bb70 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a  ps in the list..
1bb80 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1bb90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1bba0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1bbb0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1bbc0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1bbd0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1bbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bbf0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1bc00 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1bc10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31  S:.**.** {F13601
1bc20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
1bc30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1bc40 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  unt(S)] interfac
1bc50 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
1bc60 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73        the larges
1bc70 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53  t index of all S
1bc80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  QL parameters in
1bc90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1bca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1bcb0 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66  ment] S, or 0 if
1bcc0 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63   S.**          c
1bcd0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
1bce0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
1bcf0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1bd00 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
1bd10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1bd20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bd30 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
1bd40 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30  arameter {F13620
1bd50 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
1bd60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1bd70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
1bd80 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
1bd90 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1bda0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
1bdb0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
1bdc0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
1bdd0 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20  the form ":AAA" 
1bde0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
1bdf0 41 41 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a  AA" have a name.
1be00 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ** which is the 
1be10 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72  string ":AAA" or
1be20 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
1be30 22 2e 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ". .** In other 
1be40 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1be50 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1be60 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "@".** is inclu
1be70 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
1be80 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61  he name..** Para
1be90 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
1bea0 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22  rm "?" or "?NNN"
1beb0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a   have no name..*
1bec0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
1bed0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
1bee0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
1bef0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
1bf00 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
1bf10 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
1bf20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
1bf30 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
1bf40 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
1bf50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
1bf60 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1bf70 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
1bf80 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1bf90 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
1bfa0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
1bfb0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
1bfc0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
1bfd0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
1bfe0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1bff0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
1c000 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1c010 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1c020 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1c030 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1c040 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1c050 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1c060 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1c070 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1c080 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1c090 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1c0a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32  TS:.**.** {F1362
1c0b0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1c0c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1c0d0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
1c0e0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
1c0f0 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
1c100 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1c110 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
1c120 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
1c130 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1c140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1c150 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
1c160 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1c170 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
1c180 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
1c190 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
1c1a0 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
1c1b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
1c1c0 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
1c1d0 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
1c1e0 6d 65 74 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20  meter "?" or.** 
1c1f0 20 20 20 20 20 20 20 20 20 61 20 6e 75 6d 62 65           a numbe
1c200 72 65 64 20 70 61 72 61 6d 65 74 65 72 20 22 3f  red parameter "?
1c210 4e 4e 4e 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  NNN"..*/.const c
1c220 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
1c230 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1c240 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1c250 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
1c260 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
1c270 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
1c280 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46   A Given Name {F
1c290 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13640}.**.** Ret
1c2a0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
1c2b0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
1c2c0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
1c2d0 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
1c2e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
1c2f0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
1c300 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
1c310 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1c320 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1c330 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1c340 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
1c350 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1c360 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1c370 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1c380 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1c390 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1c3a0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1c3b0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1c3c0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1c3d0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1c3e0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1c3f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1c400 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1c410 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1c420 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1c430 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1c440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1c450 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1c460 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1c470 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1c480 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1c490 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1c4a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20  .**.** {F13641} 
1c4b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
1c4c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1c4d0 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
1c4e0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
1c4f0 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
1c500 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1c510 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1c520 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
1c530 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d       S whose nam
1c540 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54  e matches the UT
1c550 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72  F-8 string N, or
1c560 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a   0 if there is.*
1c570 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61  *          no ma
1c580 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tch..*/.int sqli
1c590 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1c5a0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1c5b0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1c5c0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1c5d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1c5e0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
1c5f0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
1c600 61 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d  atement {F13660}
1c610 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
1c620 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
1c630 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
1c640 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
1c650 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68   not.** reset th
1c660 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1c670 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
1c680 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61   on a .** [prepa
1c690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1c6a0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
1c6b0 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c  e to.** reset al
1c6c0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
1c6d0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
1c6e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1c6f0 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20  ** {F13661} The 
1c700 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
1c710 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65  indings(S)] inte
1c720 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c  rface resets all
1c730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1c740 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69   parameter bindi
1c750 6e 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ngs in [prepared
1c760 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
1c770 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
1c780 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1c790 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
1c7a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
1c7b0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1c7c0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
1c7d0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
1c7e0 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30  sult Set {F13710
1c7f0 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
1c800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1c810 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
1c820 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
1c830 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  by the .** [prep
1c840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1c850 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1c860 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53  turns 0.** if pS
1c870 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
1c880 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1c890 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1c8a0 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70  a (for .** examp
1c8b0 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a  le an UPDATE)..*
1c8c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1c8d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20  .**.** {F13711} 
1c8e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1c8f0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  umn_count(S)] in
1c900 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1c910 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1c920 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
1c930 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1c940 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79  set generated by
1c950 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1c970 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66  ment] S, or 0 if
1c980 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65   S does not gene
1c990 72 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rate.**         
1c9a0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
1c9b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1c9c0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
1c9d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1c9e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c9f0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
1ca00 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1ca10 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13720}.**.** Th
1ca20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1ca30 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
1ca40 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
1ca50 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
1ca60 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1ca70 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1ca80 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
1ca90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1caa0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1cab0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1cac0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1cad0 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
1cae0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
1caf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1cb00 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1cb10 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1cb20 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1cb30 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
1cb40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1cb50 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  is the.** [prepa
1cb60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1cb70 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
1cb80 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
1cb90 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ent..** The seco
1cba0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1cbb0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  the column numbe
1cbc0 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  r.  The left-mos
1cbd0 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e  t column is.** n
1cbe0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
1cbf0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1cc00 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
1cc10 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
1cc20 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
1cc30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
1cc40 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
1cc50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1cc60 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  )].** or until t
1cc70 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c  he next call sql
1cc80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1cc90 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
1cca0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a  lumn_name16().**
1ccb0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
1ccc0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71  umn..**.** If sq
1ccd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
1cce0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
1ccf0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
1cd00 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
1cd10 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
1cd20 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
1cd30 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
1cd40 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
1cd50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
1cd60 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1cd70 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72   The name of a r
1cd80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
1cd90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1cda0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
1cdb0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
1cdc0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1cdd0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
1cde0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
1cdf0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
1ce00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
1ce10 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
1ce20 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
1ce30 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
1ce40 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
1ce50 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
1ce60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1ce70 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20  *.** {F13721} A 
1ce80 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
1ce90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
1cea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1ceb0 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  e(S,N)].**      
1cec0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
1ced0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
1cee0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1cef0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
1cf00 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
1cf10 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
1cf20 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
1cf30 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
1cf40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1cf50 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
1cf60 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1cf70 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1cf80 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
1cf90 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66  3723} A successf
1cfa0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
1cfb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1cfc0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
1cfd0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1cfe0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1cff0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1d000 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20       of the Nth 
1d010 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
1d020 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74  is the left-most
1d030 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
1d040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
1d050 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
1d060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d070 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S as a.**       
1d080 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
1d090 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
1d0a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d0b0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
1d0c0 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {F13724} The [s
1d0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d0e0 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
1d0f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1d100 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1d110 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
1d120 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
1d130 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
1d140 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
1d150 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
1d160 72 79 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ry memory to hol
1d170 64 20 74 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72  d there normal r
1d180 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a  eturn strings..*
1d190 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66  *.** {F13725} If
1d1a0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
1d1b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
1d1c0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f  umn_name(S,N)] o
1d1d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1d1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1d1f0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75  me16(S,N)] is ou
1d200 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e  t of range, then
1d210 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1d220 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1d230 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1d240 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37  er..** .** {F137
1d250 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
1d260 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1d270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1d280 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
1d290 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1d2a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
1d2b0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
1d2c0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
1d2d0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
1d2e0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
1d2f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
1d300 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
1d310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1d320 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
1d330 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
1d340 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alled..**.** {F1
1d350 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
1d360 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
1d370 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1d380 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
1d390 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
1d3a0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
1d3b0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
1d3c0 20 74 68 65 20 69 6e 64 65 6e 74 69 66 69 65 72   the indentifier
1d3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1d3e0 74 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65  the right of the
1d3f0 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a   AS keyword..*/.
1d400 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1d410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1d420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1d430 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
1d440 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1d450 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1d460 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
1d470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d480 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
1d490 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
1d4a0 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a  t {F13740}.**.**
1d4b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d4c0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
1d4d0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
1d4e0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
1d4f0 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
1d500 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
1d510 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54  sult of a SELECT
1d520 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
1d530 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
1d540 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1d550 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1d560 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1d570 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1d580 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46  er a UTF8 or UTF
1d590 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
1d5a0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
1d5b0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
1d5c0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
1d5d0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
1d5e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1d5f0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
1d600 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
1d610 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1d620 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
1d630 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
1d640 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
1d650 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70   until.** the [p
1d660 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d670 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  t] is destroyed 
1d680 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1d690 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1d6a0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
1d6b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
1d6c0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
1d6d0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
1d6e0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
1d6f0 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
1d700 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
1d710 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
1d720 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
1d730 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
1d740 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
1d750 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1d760 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
1d770 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
1d780 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1d790 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65  ement]..** These
1d7a0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1d7b0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
1d7c0 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  out the Nth colu
1d7d0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  mn returned by .
1d7e0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
1d7f0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1d800 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
1d810 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
1d820 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
1d830 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
1d840 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1d850 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  an expression.**
1d860 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e 64   or subquery and
1d870 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
1d880 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
1d890 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
1d8a0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55  ons.** return NU
1d8b0 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  LL.  These routi
1d8c0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
1d8d0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
1d8e0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
1d8f0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
1d900 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68  .  Otherwise, th
1d910 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a  ey return the .*
1d920 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  * name of the at
1d930 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
1d940 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1d950 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
1d960 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61  ult.** column wa
1d970 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
1d980 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
1d990 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
1d9a0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
1d9b0 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
1d9c0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
1d9d0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
1d9e0 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
1d9f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
1da00 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
1da10 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
1da20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
1da30 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
1da40 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1da50 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45  the .** SQLITE_E
1da60 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
1da70 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
1da80 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
1da90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31  d..**.** {U13751
1daa0 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  }.** If two or m
1dab0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
1dac0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
1dad0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1dae0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
1daf0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
1db00 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
1db10 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
1db20 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
1db30 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
1db40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
1db50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1db60 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3741} The [sqlit
1db70 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1db80 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  se_name(S,N)] in
1db90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1dba0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1dbb0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1dbc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1dbd0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1dbe0 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
1dbf0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
1dc00 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
1dc10 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1dc20 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
1dc30 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
1dc40 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
1dc50 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  the the Nth colu
1dc60 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
1dc70 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
1dc80 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
1dc90 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
1dca0 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
1dcb0 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
1dcc0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
1dcd0 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
1dce0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
1dcf0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1dd00 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
1dd10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1dd20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1dd30 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
1dd40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
1dd50 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1dd60 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
1dd70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1dd80 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1dd90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1dda0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1ddb0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1ddc0 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1ddd0 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1dde0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1ddf0 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1de00 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1de10 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1de20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1de30 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1de40 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1de50 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1de60 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1de70 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1de80 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1de90 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
1dea0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
1deb0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1dec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ded0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1dee0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1def0 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
1df00 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1df10 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1df20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1df30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1df40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1df50 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1df60 55 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e  ULL if the the N
1df70 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
1df80 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1df90 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
1dfa0 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
1dfb0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1dfc0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
1dfd0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
1dfe0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
1dff0 2a 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b  * {F13744} The [
1e000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1e010 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  able_name16(S,N)
1e020 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1e030 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1e040 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1e050 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1e060 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1e070 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e080 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
1e090 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
1e0a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
1e0b0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
1e0c0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1e0d0 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
1e0e0 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
1e0f0 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
1e100 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  the the Nth colu
1e110 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
1e120 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
1e130 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
1e140 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
1e150 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
1e160 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
1e170 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
1e180 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
1e190 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
1e1a0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1e1b0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
1e1c0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
1e1d0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
1e1e0 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
1e1f0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1e200 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1e210 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
1e220 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
1e230 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
1e240 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1e250 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
1e260 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
1e270 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
1e280 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  the the Nth colu
1e290 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
1e2a0 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
1e2b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
1e2c0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
1e2d0 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
1e2e0 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
1e2f0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
1e300 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
1e310 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  46} The [sqlite3
1e320 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1e330 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
1e340 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1e350 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1e360 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
1e370 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
1e380 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1e390 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1e3a0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1e3b0 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  mn from which th
1e3c0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  e .**          N
1e3d0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
1e3e0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
1e3f0 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20  atement] S .**  
1e400 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61          is extra
1e410 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
1e420 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c   the the Nth col
1e430 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a  umn of S is a.**
1e440 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61            genera
1e450 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
1e460 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
1e470 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
1e480 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
1e490 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20  e the name..**  
1e4a0 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33          .** {F13
1e4b0 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20  748} The return 
1e4c0 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20  values from.**  
1e4d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e4e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1e4f0 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74  _name|column met
1e500 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
1e510 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1e520 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20  e valid.**      
1e530 20 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65      for the life
1e540 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
1e550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e570 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
1e580 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
1e590 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
1e5a0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
1e5b0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
1e5c0 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
1e5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
1e5e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c   column..**.** L
1e5f0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
1e600 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77  * {U13751} If tw
1e610 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1e620 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1e630 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
1e640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1e650 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c  atabase_name|col
1e660 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
1e670 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
1e680 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70       the same [p
1e690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e6a0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
1e6b0 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
1e6c0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
1e6d0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
1e6e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
1e6f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
1e700 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1e710 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
1e720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e730 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1e750 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
1e760 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1e770 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1e780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1e790 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
1e7a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e7b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1e7c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
1e7d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1e7e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
1e7f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1e800 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
1e810 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
1e840 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
1e850 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
1e860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e870 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
1e880 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
1e890 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a  ult {F13760}.**.
1e8a0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1e8b0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
1e8c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e8d0 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  . .** If this st
1e8e0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c  atement is a SEL
1e8f0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  ECT statement an
1e900 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
1e910 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75   of the .** retu
1e920 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
1e930 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69  of that SELECT i
1e940 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
1e950 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
1e960 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
1e970 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
1e980 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
1e990 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
1e9a0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
1e9b0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1e9c0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
1e9d0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
1e9e0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1e9f0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
1ea00 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1ea10 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
1ea20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
1ea30 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
1ea40 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a  oded.  {END} .**
1ea50 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   For example, in
1ea60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1ea70 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
1ea80 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
1ea90 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41  ARIANT);.**.** A
1eaa0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
1eab0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1eac0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
1ead0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
1eae0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e  M t1;.**.** Then
1eaf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
1eb00 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
1eb10 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
1eb20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  for the second.*
1eb30 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  * result column 
1eb40 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
1eb50 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
1eb60 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
1eb70 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29  column.** (i==0)
1eb80 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
1eb90 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
1eba0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
1ebb0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
1ebc0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
1ebd0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
1ebe0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
1ebf0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
1ec00 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
1ec10 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
1ec20 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
1ec30 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
1ec40 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
1ec50 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
1ec60 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
1ec70 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
1ec80 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
1ec90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1eca0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
1ecb0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
1ecc0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
1ecd0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
1ece0 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  e values..**.** 
1ecf0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ed00 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75  * {F13761}  A su
1ed10 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1ed20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ed30 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a  _decltype(S,N)].
1ed40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
1ed50 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
1ed60 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1ed70 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
1ed80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
1ed90 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
1eda0 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
1edb0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
1edc0 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
1edd0 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
1ede0 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
1edf0 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
1ee00 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
1ee10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
1ee20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ee30 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
1ee40 37 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66  762}  A successf
1ee50 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1ee60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
1ee70 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20  ype16(S,N)].**  
1ee80 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
1ee90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1eea0 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
1eeb0 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69   byte order stri
1eec0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
1eed0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
1eee0 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65  eclared datatype
1eef0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1ef00 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
1ef10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  s.**           a
1ef20 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  s the Nth column
1ef30 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20   (numbered from 
1ef40 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
1ef50 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20   set to the.**  
1ef60 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1ef70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
1ef80 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20  .**.** {F13763} 
1ef90 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
1efa0 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65  an 0 or N is gre
1efb0 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
1efc0 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  al to.**        
1efd0 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66     the number of
1efe0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65   columns in [pre
1eff0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f000 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20   S.**           
1f010 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  or if the Nth co
1f020 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20  lumn of S is an 
1f030 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1f040 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a  bquery rather.**
1f050 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20             than 
1f060 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f  a table column o
1f070 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
1f080 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
1f090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
1f0a0 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f  curs during enco
1f0b0 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73  ding conversions
1f0c0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
1f0d0 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71      calls to [sq
1f0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1f0f0 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  ltype(S,N)] or.*
1f100 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
1f110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1f120 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74  type16(S,N)] ret
1f130 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e  urn NULL..*/.con
1f140 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f150 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
1f160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1f170 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
1f180 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1f190 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
1f1a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
1f1b0 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  /* .** CAPI3REF:
1f1c0 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51    Evaluate An SQ
1f1d0 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
1f1e0 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  200}.**.** After
1f1f0 20 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   an [prepared st
1f200 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
1f210 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20  n prepared with 
1f220 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74  a call.** to eit
1f230 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1f240 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
1f250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f260 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65  _v2()] or to one
1f270 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63   of.** the legac
1f280 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
1f290 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1f2a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1f2b0 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68  pare16()],.** th
1f2c0 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  en this function
1f2d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1f2e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1f2f0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
1f300 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  e .** statement.
1f310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
1f320 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
1f330 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74  or of this sqlit
1f340 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
1f350 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
1f360 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
1f370 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
1f380 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
1f390 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
1f3a0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
1f3b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1f3c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f3d0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
1f3e0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
1f3f0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
1f400 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
1f410 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1f420 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
1f430 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
1f440 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
1f450 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
1f460 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
1f470 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
1f480 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
1f490 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
1f4a0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
1f4b0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61  *.** In the laga
1f4c0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
1f4d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
1f4e0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
1f4f0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a  QLITE_BUSY], .**
1f500 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
1f510 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
1f520 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
1f530 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1f540 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
1f550 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
1f560 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
1f570 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
1f580 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b  lt code].** or [
1f590 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
1f5a0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
1f5b0 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20  ult code] might 
1f5c0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
1f5d0 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  * well..**.** [S
1f5e0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
1f5f0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
1f600 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
1f610 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
1f620 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1f630 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
1f640 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
1f650 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
1f660 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20   is a COMMIT.** 
1f670 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
1f680 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
1f690 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
1f6a0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
1f6b0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1f6c0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
1f6d0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f  ment is not a CO
1f6e0 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20  MMIT and occurs 
1f6f0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
1f700 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1f710 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
1f720 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
1f730 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
1f740 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
1f750 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
1f760 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
1f770 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
1f780 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
1f790 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
1f7a0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
1f7b0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
1f7c0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
1f7d0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
1f7e0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
1f7f0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
1f800 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f810 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
1f820 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
1f830 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
1f840 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
1f850 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
1f860 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
1f870 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
1f880 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a  any data, then .
1f890 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ** [SQLITE_ROW] 
1f8a0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
1f8b0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
1f8c0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
1f8d0 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69  .** for processi
1f8e0 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ng by the caller
1f8f0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
1f900 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
1f910 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
1f920 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
1f930 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
1f940 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
1f950 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
1f960 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
1f970 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
1f980 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
1f990 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
1f9a0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
1f9b0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
1f9c0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
1f9d0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
1f9e0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
1f9f0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
1fa00 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
1fa10 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
1fa20 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
1fa30 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
1fa40 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
1fa50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
1fa60 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
1fa70 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
1fa80 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
1fa90 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
1faa0 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53   (example:.** [S
1fab0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1fac0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1fad0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
1fae0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
1faf0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
1fb00 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
1fb10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fb20 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
1fb30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1fb40 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
1fb50 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
1fb60 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
1fb70 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
1fb80 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
1fb90 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
1fba0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
1fbb0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
1fbc0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
1fbd0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
1fbe0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
1fbf0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
1fc00 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
1fc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fc20 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
1fc30 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
1fc40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
1fc50 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
1fc60 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a  n one that had .
1fc70 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
1fc80 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
1fc90 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
1fca0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
1fcb0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
1fcc0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
1fcd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fce0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
1fcf0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
1fd00 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
1fd10 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
1fd20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
1fd30 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
1fd40 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a  ce Alert:</b>.**
1fd50 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
1fd60 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68  nterface, .** th
1fd70 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
1fd80 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
1fd90 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
1fda0 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51  ror code,.** [SQ
1fdb0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
1fdc0 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72  lowing any error
1fdd0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1fde0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64  ITE_BUSY].** and
1fdf0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1fe00 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
1fe10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fe20 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1fe30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
1fe40 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
1fe50 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66  ne of the specif
1fe60 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ic.** [error cod
1fe70 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
1fe80 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1fe90 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
1fea0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
1feb0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
1fec0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
1fed0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
1fee0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
1fef0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
1ff00 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
1ff10 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
1ff20 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
1ff30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ff40 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1ff50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ff60 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
1ff70 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
1ff80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ff90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1ffa0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
1ffb0 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70   the .** more sp
1ffc0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
1ffd0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
1ffe0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
1fff0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
20000 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
20010 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
20020 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
20030 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
20040 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d  :.**.** {F13202}
20050 20 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73    If [prepared s
20060 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72  tatement] S is r
20070 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20  eady to be.**   
20080 20 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65          run, the
20090 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
200a0 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61  S)] advances tha
200b0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
200c0 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
200d0 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c    until to compl
200e0 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69  etion or until i
200f0 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65  t is ready to re
20100 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20  turn another.** 
20110 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66            row of
20120 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20130 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20  or an interrupt 
20140 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f  or run-time erro
20150 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
20160 7b 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61  {F15304}  When a
20170 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20180 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65  3_step(S)] cause
20190 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  s the .**       
201a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
201b0 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75  atement] S to ru
201c0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c  n to completion,
201d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
201e0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
201f0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ns [SQLITE_DONE]
20200 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d  ..**.** {F15306}
20210 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
20220 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
20230 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65  )] stops because
20240 20 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20   it is ready.** 
20250 20 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74            to ret
20260 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  urn another row 
20270 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20280 74 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a  t, it returns.**
20290 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
202a0 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  TE_ROW]..**.** {
202b0 46 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61  F15308}  If a ca
202c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
202d0 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65  tep(S)] encounte
202e0 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rs an.**        
202f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65     [sqlite3_inte
20300 72 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d  rrupt|interrupt]
20310 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
20320 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
20330 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e     it returns an
20340 20 61 70 70 72 6f 70 72 61 69 74 65 20 65 72 72   appropraite err
20350 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20  or code that is 
20360 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20  not one of.**   
20370 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
20380 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  OK], [SQLITE_ROW
20390 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  ], or [SQLITE_DO
203a0 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  NE]..**.** {F153
203b0 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69  10}  If an [sqli
203c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e  te3_interrupt|in
203d0 74 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d  terrupt] or run-
203e0 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20  time error.**   
203f0 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
20400 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  uring a call to 
20410 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
20420 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  ].**           f
20430 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  or a [prepared s
20440 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61  tatement] S crea
20450 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
20460 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e         legacy in
20470 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
20480 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
20490 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
204a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
204b0 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
204c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
204d0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
204e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
204f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
20500 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
20510 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
20520 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
20530 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
20540 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
20550 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
20560 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37  result set {F137
20570 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  70}.**.** Return
20580 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
20590 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
205a0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
205b0 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
205c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
205d0 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66  .** {F13771}  Af
205e0 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
205f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
20600 74 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  that returns.** 
20610 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
20620 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c  E_ROW], the [sql
20630 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
20640 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20  S)] routine.**  
20650 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65           will re
20660 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
20670 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20  lue as the.**   
20680 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20690 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
206a0 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ] function..**.*
206b0 2a 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65  * {F13772}  Afte
206c0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
206d0 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  S)] has returned
206e0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
206f0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
20700 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20     [SQLITE_ROW] 
20710 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  or before [sqlit
20720 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
20730 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  been .**        
20740 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65     called on the
20750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20760 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  ment] for.**    
20770 20 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74         the first
20780 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77   time since it w
20790 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  as [sqlite3_prep
207a0 61 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a  are|prepared].**
207b0 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73             or [s
207c0 71 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73  qlite3_reset|res
207d0 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  et], the [sqlite
207e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
207f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f  .**           ro
20800 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
20810 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ro..*/.int sqlit
20820 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
20830 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
20840 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
20850 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
20860 20 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32   Datatypes {F102
20870 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  65}.** KEYWORDS:
20880 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
20890 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79  ** {F10266}Every
208a0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
208b0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
208c0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
208d0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
208e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
208f0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
20900 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
20910 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
20920 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
20930 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
20940 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
20950 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
20960 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
20970 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
20980 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
20990 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
209a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
209b0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
209c0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
209d0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
209e0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
209f0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
20a00 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
20a10 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
20a20 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
20a30 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
20a40 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
20a50 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
20a60 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
20a70 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
20a80 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
20a90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
20aa0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
20ab0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
20ac0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
20ad0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
20ae0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
20af0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
20b00 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
20b10 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
20b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
20b30 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
20b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
20b50 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
20b60 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
20b70 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  ts Values From A
20b80 20 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a   Query {F13800}.
20b90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
20ba0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
20bb0 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
20bc0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
20bd0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
20be0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
20bf0 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73  ion about.** a s
20c00 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
20c10 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
20c20 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
20c30 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20  y.  In every.** 
20c40 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
20c50 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
20c60 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  nter to the .** 
20c70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20c80 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
20c90 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  ng.** evaluated 
20ca0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
20cb0 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65  mt*] that was re
20cc0 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  turned from .** 
20cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ce0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
20cf0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61   its variants) a
20d00 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  nd.** the second
20d10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
20d20 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
20d30 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
20d40 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73  nformation .** s
20d50 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
20d60 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  d.  The left-mos
20d70 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
20d80 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61  result set.** ha
20d90 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e  s an index of 0.
20da0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
20db0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  L statement is n
20dc0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
20dd0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
20de0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
20df0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  the column index
20e00 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
20e10 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
20e20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54  undefined. .** T
20e30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
20e40 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
20e50 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
20e60 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
20e70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20e80 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
20e90 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
20ea0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
20eb0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
20ec0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20ed0 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ze()] has been c
20ee0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79  all subsequently
20ef0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
20f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
20f10 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
20f20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20f30 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
20f40 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
20f50 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
20f60 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
20f70 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
20f80 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
20f90 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
20fa0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
20fb0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
20fc0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
20fd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20fe0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
20ff0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
21000 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
21010 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
21020 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
21030 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
21040 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
21050 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
21060 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a  ndefined.  .**.*
21070 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
21080 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
21090 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  ine returns .** 
210a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
210b0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
210c0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
210d0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
210e0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
210f0 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  mn.  The returne
21100 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
21110 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
21120 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
21130 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
21140 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
21150 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
21160 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
21170 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
21180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21190 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
211a0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
211b0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
211c0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
211d0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
211e0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
211f0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
21200 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
21210 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
21220 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
21230 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
21240 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
21250 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
21260 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
21270 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
21280 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
21290 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
212a0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
212b0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
212c0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
212d0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
212e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
212f0 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f  n_bytes() .** ro
21300 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21310 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
21320 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
21330 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
21340 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
21350 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
21360 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
21370 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
21380 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
21390 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
213a0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
213b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
213c0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
213d0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
213e0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
213f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
21400 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
21410 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
21420 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
21430 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
21440 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
21450 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
21460 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
21470 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
21480 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
21490 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
214a0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
214b0 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
214c0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
214d0 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
214e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
214f0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
21500 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
21510 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
21520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
21530 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
21540 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
21550 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
21560 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
21570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21580 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
21590 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
215a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
215b0 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
215c0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
215d0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
215e0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
215f0 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20  ero-length blob 
21600 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
21610 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
21620 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
21630 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
21640 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
21650 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
21660 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
21670 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21680 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
21690 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
216a0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
216b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
216c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
216d0 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72  -8.  .** The zer
216e0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
216f0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
21700 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
21710 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
21720 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
21730 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
21740 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
21750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
21760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
21770 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
21780 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
21790 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
217a0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
217b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
217c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
217d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
217e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
217f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
21800 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
21810 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
21820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
21830 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
21840 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
21850 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
21860 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
21870 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  like .** [sqlite
21880 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
21890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
218a0 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  ext()], or [sqli
218b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
218c0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
218d0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
218e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
218f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
21900 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
21910 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
21920 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
21930 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
21940 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
21950 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
21960 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
21970 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
21980 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
21990 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
219a0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
219b0 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72  to do the conver
219c0 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  sion.** automati
219d0 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
219e0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
219f0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
21a00 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ons that.** are 
21a10 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
21a20 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
21a30 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
21a40 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
21a50 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
21a60 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
21a70 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
21a80 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
21a90 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
21aa0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
21ab0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
21ac0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
21ad0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
21ae0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
21af0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
21b00 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
21b10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
21b20 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
21b30 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
21b40 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
21b50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
21b60 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
21b70 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
21b80 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
21b90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
21ba0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
21bb0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
21bc0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
21bd0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
21be0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
21bf0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
21c00 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
21c10 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
21c20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
21c30 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45  me as for INTEGE
21c40 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
21c50 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
21c60 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
21c70 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
21c80 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
21c90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
21ca0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
21cb0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
21cc0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
21cd0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
21ce0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
21cf0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
21d00 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
21d10 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
21d20 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
21d30 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
21d40 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
21d50 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
21d60 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
21d70 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
21d80 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
21d90 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
21da0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
21db0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
21dc0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
21dd0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
21de0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
21df0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
21e00 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
21e10 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
21e20 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
21e30 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
21e40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
21e50 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
21e60 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
21e70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
21e80 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
21e90 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
21ea0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
21eb0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
21ec0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
21ed0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
21ee0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
21ef0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
21f00 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
21f10 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
21f20 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
21f30 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20  t has its.** on 
21f40 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72  equavalent inter
21f50 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
21f60 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
21f70 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
21f80 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
21f90 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
21fa0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
21fb0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
21fc0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
21fd0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
21fe0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
21ff0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
22000 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
22010 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
22020 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
22030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
22040 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
22050 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
22060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22070 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
22080 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
22090 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
220a0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
220b0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
220c0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
220d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
220e0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
220f0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
22100 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
22110 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
22120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22130 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
22140 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
22150 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
22160 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
22170 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
22180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
22190 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
221a0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
221b0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
221c0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
221d0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
221e0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
221f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22200 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
22210 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
22220 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
22230 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
22240 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
22250 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
22260 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
22270 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
22280 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
22290 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
222a0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
222b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
222c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
222d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
222e0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
222f0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
22300 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
22310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
22320 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
22330 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
22340 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
22350 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
22360 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
22370 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
22380 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
22390 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
223a0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
223b0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
223c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
223d0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
223e0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
223f0 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
22400 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
22410 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
22420 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
22430 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
22440 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
22450 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
22460 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
22470 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
22480 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
22490 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
224a0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
224b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
224c0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
224d0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
224e0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
224f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
22500 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
22510 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
22520 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
22530 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
22540 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
22550 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22560 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
22570 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
22580 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
22590 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
225a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
225b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
225c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
225d0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
225e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
225f0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
22600 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
22610 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
22620 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
22630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22640 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
22650 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
22660 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
22670 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
22680 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
22690 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
226a0 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
226b0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
226c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
226d0 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
226e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
226f0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
22700 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
22710 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
22720 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
22730 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
22740 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22750 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
22760 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
22770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
22780 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
22790 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
227a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
227b0 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
227c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
227d0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
227e0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
227f0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
22800 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
22810 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
22820 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
22830 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
22840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22850 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
22860 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
22870 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22880 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
22890 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
228a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
228b0 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
228c0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
228d0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
228e0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
228f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
22900 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
22910 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
22920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22930 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
22940 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
22950 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
22960 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
22970 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
22980 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
22990 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
229a0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
229b0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
229c0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
229d0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
229e0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
229f0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
22a00 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
22a10 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
22a20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
22a30 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
22a40 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
22a50 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
22a60 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
22a70 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
22a80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22a90 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54  **.** {F13803} T
22aa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
22ab0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
22ac0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
22ad0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22ae0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
22af0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
22b00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22b10 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
22b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22b30 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62  ment] S into a b
22b40 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
22b50 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
22b60 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
22b70 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
22b80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36  e..**.** {F13806
22b90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
22ba0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
22bb0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
22bc0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
22bd0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
22be0 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20  tes in the blob 
22bf0 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
22c00 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
22c10 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
22c20 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
22c30 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
22c40 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
22c50 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
22c60 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
22c70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22c80 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
22c90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22ca0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
22cb0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ,N)]..**.** {F13
22cc0 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
22cd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22ce0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
22cf0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
22d00 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
22d10 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
22d20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
22d30 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
22d40 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
22d50 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
22d60 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
22d70 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
22d80 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
22d90 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
22da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
22db0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
22dc0 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {F13812} The [s
22dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
22de0 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
22df0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
22e00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
22e10 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
22e20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
22e30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
22e40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
22e50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22e60 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
22e70 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
22e80 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
22e90 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
22ea0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
22eb0 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68  *.** {F13815} Th
22ec0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22ed0 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
22ee0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
22ef0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
22f00 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
22f10 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
22f20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
22f30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22f50 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d  nt] S into a 64-
22f60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
22f70 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
22f80 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
22f90 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
22fa0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
22fb0 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65  .** {F13818} The
22fc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22fd0 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74  _int64(S,N)] int
22fe0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
22ff0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23000 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
23010 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
23020 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23030 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
23040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23050 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
23060 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
23070 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
23080 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
23090 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
230a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  er..**.** {F1382
230b0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
230c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
230d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
230e0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
230f0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
23100 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
23110 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
23120 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
23130 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
23140 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
23150 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
23160 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20  ed UTF-8 .**    
23170 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
23180 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
23190 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
231a0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34  g..**.** {F13824
231b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
231c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
231d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
231e0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
231f0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
23200 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
23210 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
23220 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
23230 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
23240 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
23250 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
23260 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
23270 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
23280 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
23290 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
232a0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
232b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
232c0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
232d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20  .**.** {F13827} 
232e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
232f0 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69  umn_type(S,N)] i
23300 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
23320 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
23330 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
23340 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
23350 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
23360 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
23370 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
23380 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
23390 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
233a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69  the Nth column i
233b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
233c0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
233d0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
233e0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
233f0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
23400 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b  * {F13830} The [
23410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
23420 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
23430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
23440 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
23450 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
23460 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23470 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
23480 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23490 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
234a0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
234b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
234c0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
234d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
234e0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
234f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23500 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
23510 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23520 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
23530 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
23540 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23550 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
23560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23570 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
23580 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
23590 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
235a0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
235b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
235c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
235d0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
235e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
235f0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
23600 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
23610 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
23620 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23630 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
23640 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
23650 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
23660 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23670 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
23680 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23690 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
236a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
236b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
236c0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
236d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
236e0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
236f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23700 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
23710 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
23720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23730 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
23740 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
23750 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
23760 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23770 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
23780 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
23790 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b  o delete a .** [
237a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
237b0 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74  nt]. If the stat
237c0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65  ement was.** exe
237d0 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
237e0 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  ly, or not execu
237f0 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
23800 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
23810 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78  turned..** If ex
23820 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
23830 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
23840 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72  then an .** [err
23850 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
23860 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
23870 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
23880 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  . .**.** This ro
23890 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
238a0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
238b0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
238c0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
238d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
238e0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
238f0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
23900 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65  s not .** comple
23910 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
23920 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
23930 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
23940 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
23950 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
23960 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74   or an interrupt
23970 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33  .  (See [sqlite3
23980 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20  _interrupt()].) 
23990 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
239a0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
239b0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
239c0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
239d0 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e  lled,  .** depen
239e0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
239f0 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
23a00 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  he .** [error co
23a10 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
23a20 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
23a30 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  RT]..**.** INVAR
23a40 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
23a50 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1302} The [sqlit
23a60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
23a70 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f  interface destro
23a80 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ys the.**       
23a90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
23aa0 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65  tement] S and re
23ab0 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20  leases all.**   
23ac0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e         memory an
23ad0 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73  d file resources
23ae0 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62   held by that ob
23af0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ject..**.** {F11
23b00 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  304} If the most
23b10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
23b20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
23b30 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
23b40 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
23b50 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
23b60 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a  urned an error,.
23b70 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
23b80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23b90 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74  ze(S)] returns t
23ba0 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a  hat same error..
23bb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
23bc0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
23bd0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
23bf0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
23c00 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
23c10 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F13330}.**.** 
23c20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
23c30 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
23c40 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
23c50 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  a .** [prepared 
23c60 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
23c70 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74  t..** back to it
23c80 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
23c90 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
23ca0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
23cb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
23cc0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
23cd0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
23ce0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
23cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
23d00 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
23d10 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
23d20 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
23d30 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
23d40 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
23d50 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
23d60 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
23d70 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20  ** {F11332} The 
23d80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
23d90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
23da0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
23db0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
23dc0 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
23dd0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
23de0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
23df0 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20  .**.** {F11334} 
23e00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
23e10 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
23e20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
23e30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70   .**          [p
23e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23e50 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
23e60 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
23e70 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
23e80 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
23e90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
23ea0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
23eb0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
23ec0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
23ed0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
23ee0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
23ef0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
23f00 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74  ** {F11336} If t
23f10 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
23f20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
23f30 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20  step(S)] for.** 
23f40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23f60 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
23f70 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
23f80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
23f90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
23fa0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
23fb0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
23fc0 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20  ** {F11338} The 
23fd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
23fe0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
23ff0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
24000 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
24010 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
24020 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
24030 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70  ndings] on [prep
24040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24050 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
24060 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
24070 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
24080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24090 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
240a0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20  e SQL Functions 
240b0 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F16100}.** KEYW
240c0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
240d0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
240e0 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  s} .**.** These 
240f0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
24100 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
24110 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f  n as.** "functio
24120 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
24130 6e 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74  nes") are used t
24140 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
24150 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
24160 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66  s.** or to redef
24170 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
24180 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
24190 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
241a0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a  gregates.  The.*
241b0 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c  * difference onl
241c0 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77  y between the tw
241d0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
241e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
241f0 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  the.** name of t
24200 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
24210 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
24220 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
24230 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
24240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24250 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
24260 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  16 for sqlite3_c
24270 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
24280 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
24290 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
242a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
242b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
242c0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
242d0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
242e0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
242f0 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  ngle.** program 
24300 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
24310 6e 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ne [database con
24320 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61  nection] interna
24330 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a  lly, then SQL.**
24340 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
24350 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
24360 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64  ually to each [d
24370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24380 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  on]..**.** The s
24390 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
243a0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
243b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
243c0 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a  to be created.**
243d0 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a   or redefined..*
243e0 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * The length of 
243f0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
24400 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
24410 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
24420 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  he .** zero-term
24430 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
24440 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
24450 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
24460 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
24470 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
24480 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
24490 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
244a0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
244b0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
244c0 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
244d0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
244e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
244f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
24500 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
24510 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24520 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
24530 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
24540 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
24550 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
24560 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
24570 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
24580 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
24590 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
245a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
245b0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
245c0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
245d0 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  what .** [SQLITE
245e0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
245f0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
24600 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
24610 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
24620 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
24630 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
24640 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
24650 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
24660 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
24670 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
24680 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
24690 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
246a0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
246b0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
246c0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
246d0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
246e0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
246f0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
24700 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24710 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
24720 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
24730 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
24740 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
24750 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
24760 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
24770 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
24780 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
24790 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
247a0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
247b0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
247c0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
247d0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
247e0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
247f0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
24800 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
24810 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
24820 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
24830 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
24840 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
24850 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74  t care what.** t
24860 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
24870 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
24880 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
24890 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c  hould be.** [SQL
248a0 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
248b0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
248c0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
248d0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
248e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
248f0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74  .** of the funct
24900 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
24910 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
24920 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ter using.** [sq
24930 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
24940 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
24950 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
24960 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
24970 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
24980 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
24990 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
249a0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
249b0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
249c0 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ent the SQL.** f
249d0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
249e0 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
249f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
24a00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
24a10 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  tation of.** the
24a20 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20   xFunc callback 
24a30 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
24a40 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
24a50 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
24a60 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
24a70 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
24a80 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
24a90 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
24aa0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24ab0 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64  .** of xStep and
24ac0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
24ad0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
24ae0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
24af0 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69  delete an.** exi
24b00 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
24b10 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
24b20 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
24b30 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
24b40 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  n.** callback..*
24b50 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
24b60 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
24b70 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
24b80 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
24b90 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
24ba0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
24bb0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
24bc0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
24bd0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
24be0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
24bf0 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74  ring perferred t
24c00 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
24c10 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
24c20 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
24c30 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
24c40 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
24c50 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
24c60 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
24c70 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
24c80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
24c90 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73   {F16103} The [s
24ca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24cb0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65  nction16()] inte
24cc0 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78  rface behaves ex
24cd0 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  actly.**        
24ce0 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f    like [sqlite3_
24cf0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24d00 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
24d10 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
24d20 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24d30 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74  prets the zFunct
24d40 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ionName argument
24d50 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   as.**          
24d60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24d70 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
24d80 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
24d90 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20   of as a.**     
24da0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
24db0 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  ated UTF-8..**.*
24dc0 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63  * {F16106} A suc
24dd0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
24de0 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
24df0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    the [sqlite3_c
24e00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
24e10 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74  ,X,N,E,...)] int
24e20 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
24e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24e40 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63  replaces callbac
24e50 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b  k functions in [
24e60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24e70 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
24e80 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65     used to imple
24e90 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
24ea0 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69  ction named X wi
24eb0 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  th N parameters.
24ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
24ed0 68 61 76 69 6e 67 20 61 20 70 65 72 66 65 72 72  having a perferr
24ee0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
24ef0 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   of E..**.** {F1
24f00 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66  6109} A successf
24f10 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
24f20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24f30 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
24f40 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
24f50 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 50    replaces the P
24f60 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61  , F, S, and L va
24f70 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72  lues from any pr
24f80 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a  ior calls with.*
24f90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
24fa0 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64  ame D, X, N, and
24fb0 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a   E values..**.**
24fc0 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73   {F16112} The [s
24fd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24fe0 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d  nction(D,X,...)]
24ff0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
25000 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
25010 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20    a return code 
25020 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
25030 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e  ] if the SQL fun
25040 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a  ction name X is.
25050 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67  **          long
25060 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65  er than 255 byte
25070 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  s exclusive of t
25080 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
25090 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31  or..**.** {F1611
250a0 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73 74  8} Either F must
250b0 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61   be NULL and S a
250c0 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c  nd L are non-NUL
250d0 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20  L or else F.**  
250e0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e          is non-N
250f0 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20  ULL and S and L 
25100 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77  are NULL, otherw
25110 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ise.**          
25120 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25130 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
25140 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72  ,P,F,S,L)] retur
25150 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ns [SQLITE_ERROR
25160 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31  ]..**.** {F16121
25170 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
25180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
25190 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
251a0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
251b0 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
251c0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
251d0 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 20  _BUSY] if there 
251e0 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 20  exist [prepared 
251f0 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20  statements].**  
25200 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
25210 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
25220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25230 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  ] D..**.** {F161
25240 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
25250 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25260 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74  (D,X,N,...)] int
25270 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
25280 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
25290 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
252a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
252b0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70   parameter N (sp
252c0 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d  ecifying the num
252d0 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
252e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
252f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25300 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72 65   being registere
25310 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20  d) is less.**   
25320 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f         than -1 o
25330 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
25340 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32  27..**.** {F1612
25350 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e  7} When N is non
25360 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b  -negative, the [
25370 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25380 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
25390 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
253a0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
253b0 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
253c0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
253d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
253e0 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
253f0 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65  X when the numbe
25400 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
25410 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
25420 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  on is.**        
25430 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a    exactly N..**.
25440 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e  ** {F16130} When
25450 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73   N is -1, the [s
25460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25470 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
25480 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
25490 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
254a0 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20  callbacks to be 
254b0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20  invoked for the 
254c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
254d0 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58           named X
254e0 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72   with any number
254f0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
25500 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68  *.** {F16133} Wh
25510 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
25520 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25530 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
25540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
25550 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
25560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
25570 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
25580 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20  on X.**         
25590 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d   and when one im
255a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73  plementation has
255b0 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74   N>=0 and the ot
255c0 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a  her has N=(-1).*
255d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
255e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
255f0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20  th a non-zero N 
25600 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
25610 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65  .** {F16136} Whe
25620 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
25630 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25640 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
25650 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
25660 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
25670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
25680 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
25690 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20  ion X with.**   
256a0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
256b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
256c0 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64  nts N but with d
256d0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20  ifferent.**     
256e0 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45       encodings E
256f0 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65  , then the imple
25700 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20  mentation where 
25710 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a  E matches the.**
25720 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
25730 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70  se encoding is p
25740 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
25750 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20  {F16139} For an 
25760 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
25770 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75  nction created u
25780 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
25790 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
257a0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
257b0 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20  E,P,0,S,L)] the 
257c0 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20  finializer.**   
257d0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
257e0 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  L will always be
257f0 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
25800 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
25810 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
25820 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
25830 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
25840 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  imes..**.** {F16
25850 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
25860 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
25870 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
25880 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
25890 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
258a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
258b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
258c0 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
258d0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
258e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
258f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
25900 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
25910 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
25920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
25930 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
25940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25950 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
25960 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
25970 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25980 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f   are always [pro
25990 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
259a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
259b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
259c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
259d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
259e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
259f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
25a00 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
25a10 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
25a20 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
25a30 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
25a40 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
25a50 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
25a60 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
25a70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
25a80 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
25a90 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
25aa0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
25ab0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
25ac0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25ad0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
25ae0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
25af0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
25b00 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
25b10 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
25b20 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
25b30 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
25b40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
25b50 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
25b60 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
25b70 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
25b80 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
25b90 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
25ba0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
25bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
25bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25bd0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
25be0 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a  s {F10267}.**.**
25bf0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
25c00 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
25c10 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
25c20 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
25c30 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
25c40 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
25c50 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
25c60 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
25c70 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
25c80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
25c90 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
25ca0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
25cb0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
25cc0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
25cd0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
25ce0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
25cf0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
25d00 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
25d10 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
25d20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
25d30 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
25d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
25d50 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
25d60 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
25d70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
25d80 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
25d90 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
25da0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
25db0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
25dc0 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
25dd0 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
25de0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
25df0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
25e00 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
25e10 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
25e20 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
25e30 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
25e40 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
25e50 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
25e60 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
25e70 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
25e80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25e90 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
25ea0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
25eb0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
25ec0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
25ed0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
25ee0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
25ef0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
25f00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
25f10 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
25f20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
25f30 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
25f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
25f50 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
25f60 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
25f70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
25f80 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
25f90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
25fa0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
25fb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
25fc0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
25fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  ;.int sqlite3_me
25fe0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
25ff0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
26000 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
26010 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
26020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26030 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
26040 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
26050 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31  ter Values {F151
26060 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00}.**.** The C-
26070 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
26080 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
26090 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
260a0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
260b0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
260c0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
260d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
260e0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
260f0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
26100 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
26110 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
26120 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
26130 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
26140 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
26150 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
26160 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26170 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
26180 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26190 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
261a0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
261b0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
261c0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
261d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
261e0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
261f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
26200 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
26210 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
26220 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
26230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26240 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
26250 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
26260 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26270 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
26280 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
26290 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
262a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
262b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
262c0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
262d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
262e0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
262f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26300 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
26310 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26320 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26330 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
26340 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
26350 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
26360 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26370 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
26380 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
26390 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
263a0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
263b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
263c0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
263d0 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73  esponding .** [s
263e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
263f0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ob | sqlite3_col
26400 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20  umn_* routines] 
26410 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20  except that .** 
26420 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
26430 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
26440 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26450 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f  value] object po
26460 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64  inter.** instead
26470 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
26480 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
26490 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
264a0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
264b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
264c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
264d0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
264e0 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a   a UTF16 string.
264f0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
26500 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
26510 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
26520 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
26530 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
26540 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
26550 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
26560 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
26570 72 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e  ract UTF16 strin
26580 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
26590 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
265a0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
265b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
265c0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
265d0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
265e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
265f0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
26600 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
26610 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
26620 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
26630 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
26640 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
26650 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
26660 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
26670 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
26680 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
26690 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
266a0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
266b0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
266c0 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61   words if the va
266d0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
266e0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
266f0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
26700 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
26710 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72   is done.  Other
26720 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
26730 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  on occurs.  The 
26740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
26750 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
26760 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
26770 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
26780 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
26790 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
267a0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
267b0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
267c0 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75   that.** is retu
267d0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
267e0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
267f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26800 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
26810 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
26820 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
26830 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
26840 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26850 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
26860 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
26870 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
26880 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
26890 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
268a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
268b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
268c0 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].  .**.** These
268d0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
268e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
268f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
26900 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
26910 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
26920 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
26930 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
26940 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56  rs..**.**.** INV
26950 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26960 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  F15103} The [sql
26970 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
26980 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
26990 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
269a0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
269b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
269c0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
269d0 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72   blob and then r
269e0 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
269f0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
26a00 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
26a10 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  lue..**.** {F151
26a20 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
26a30 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
26a40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26a50 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
26a60 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
26a70 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f  es in the blob o
26a80 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
26a90 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
26aa0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
26ab0 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
26ac0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
26ad0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
26ae0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
26af0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
26b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
26b10 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
26b20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
26b30 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
26b40 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68  *.** {F15109} Th
26b50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26b60 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
26b70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26b80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
26b90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26ba0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
26bb0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
26bc0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
26bd0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
26be0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
26bf0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
26c00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
26c10 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
26c20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
26c30 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
26c40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
26c50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
26c60 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
26c70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
26c80 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  e(V)]..**.** {F1
26c90 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
26ca0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
26cb0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
26cc0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
26cd0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
26ce0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26cf0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
26d00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
26d10 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
26d20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
26d30 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
26d40 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31  ue..**.** {F1511
26d50 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
26d60 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
26d70 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
26d80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26d90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26da0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26db0 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
26dc0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26dd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
26de0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
26df0 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
26e00 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
26e10 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b  * {F15118} The [
26e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
26e30 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
26e40 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
26e50 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
26e60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26e70 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
26e80 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
26e90 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
26ea0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
26eb0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
26ec0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
26ed0 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {F15121} The [s
26ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26ef0 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
26f00 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
26f10 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
26f20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26f30 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
26f40 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
26f50 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20  ed UTF-8 .**    
26f60 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
26f70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
26f80 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
26f90 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34  g..**.** {F15124
26fa0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
26fb0 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20  alue_text16(V)] 
26fc0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
26fd0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
26fe0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
26ff0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27000 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
27010 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
27020 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
27030 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e  aligned UTF-16 n
27040 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
27050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
27060 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
27070 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
27080 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
27090 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71  {F15127} The [sq
270a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
270b0 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16be(V)] interfa
270c0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
270d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
270e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
270f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
27100 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
27110 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
27120 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
27130 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
27140 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
27150 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
27160 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
27170 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
27180 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b  * {F15130} The [
27190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
271a0 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72  xt16le(V)] inter
271b0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
271c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
271d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
271e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
271f0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
27200 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
27210 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
27220 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ed UTF-16 little
27230 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
27240 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
27250 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
27260 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
27270 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20  .**.** {F15133} 
27280 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
27290 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ue_type(V)] inte
272a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
272b0 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
272c0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
272d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
272e0 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
272f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
27300 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
27310 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
27320 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
27330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27340 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27350 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
27360 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73   {F15136} The [s
27370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
27380 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e  eric_type(V)] in
27390 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
273a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
273b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
273c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
273d0 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20  t V into either 
273e0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a  an integer or.**
273f0 20 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61            a floa
27400 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
27410 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f   if it can do so
27420 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
27430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
27440 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65  ormation, and re
27450 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51  turns one of [SQ
27460 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20  LITE_NULL],.**  
27470 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
27480 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
27490 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
274a0 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20  E_TEXT], or.**  
274b0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
274c0 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
274d0 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
274e0 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63       the [protec
274f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27500 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65  e] object V afte
27510 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  r the conversion
27520 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e   attempt..*/.con
27530 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27540 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
27550 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27560 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
27570 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
27580 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
27590 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
275a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
275b0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
275c0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
275d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
275e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
275f0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
27600 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
27610 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
27620 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
27630 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
27640 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
27650 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27670 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27680 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27690 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
276a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
276b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
276c0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
276d0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
276e0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
276f0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27700 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27710 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27720 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27730 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27740 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27750 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27770 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
27780 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
27790 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a  ntext {F16210}.*
277a0 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
277b0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
277c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
277d0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
277e0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
277f0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
27800 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
27810 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65   state.  .** The
27820 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
27830 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27840 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
27850 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c  ine is.** is cal
27860 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63  led for a partic
27870 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20  ular aggregate, 
27880 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73  SQLite allocates
27890 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72   nBytes of memor
278a0 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20  y.** zeros that 
278b0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
278c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
278d0 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e   it..** On secon
278e0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
278f0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
27900 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27910 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ext().** for the
27920 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
27930 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20  function index, 
27940 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
27950 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27960 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
27970 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67  on.** of the agg
27980 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74  regate can use t
27990 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
279a0 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
279b0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
279c0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
279d0 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
279e0 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
279f0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
27a00 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
27a10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
27a20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
27a30 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
27a40 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  f the .** [sqlit
27a50 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
27a60 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
27a70 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
27a80 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
27a90 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
27aa0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
27ab0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
27ac0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
27ad0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
27ae0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
27af0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27b00 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
27b10 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
27b20 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
27b30 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
27b40 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
27b50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20  .**.** {F16211} 
27b60 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
27b70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
27b80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27b90 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
27ba0 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
27bb0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
27bc0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
27bd0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
27be0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
27bf0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
27c00 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
27c10 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62  o allocation N b
27c20 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a  ytes of memory,.
27c30 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
27c40 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
27c50 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
27c60 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61  er to the alloca
27c70 74 69 6f 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tioned.**       
27c80 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a     memory..**.**
27c90 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d   {F16213} If a m
27ca0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
27cb0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
27cc0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
27cd0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
27ce0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
27cf0 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
27d00 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  ion returns 0..*
27d10 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65  *.** {F16215} Se
27d20 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
27d30 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
27d40 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
27d50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27d60 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
27d70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e  for the same con
27d80 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a  text pointer C.*
27d90 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72  *          ignor
27da0 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  e the N paramete
27db0 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  r and return a p
27dc0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61  ointer to the sa
27dd0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  me.**          b
27de0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72  lock of memory r
27df0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66  eturned by the f
27e00 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  irst invocation.
27e10 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20  .**.** {F16217} 
27e20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
27e30 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
27e40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27e50 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20  xt(C,N)] is.**  
27e60 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69          automati
27e70 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74  cally freed on t
27e80 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20  he next call to 
27e90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27ea0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
27eb0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27ec0 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70  ze()] for the [p
27ed0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27ee0 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a  t] containing.**
27ef0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67            the ag
27f00 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
27f10 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27f20 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76   context C..*/.v
27f30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
27f40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
27f50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27f60 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
27f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
27f80 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
27f90 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a  ctions {F16240}.
27fa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27fb0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
27fc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27fd0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
27fe0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
27ff0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
28000 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
28010 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
28020 20 6f 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c   of the the [sql
28030 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28040 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
28050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28060 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
28070 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
28080 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
28090 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
280a0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
280b0 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
280c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
280d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
280e0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
280f0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
28100 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28110 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28120 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
28130 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28140 0a 2a 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65  .** {F16243} The
28150 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
28160 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
28170 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
28180 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
28190 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
281a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
281b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
281c0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
281d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
281e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
281f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
28200 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
28210 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
28220 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
28230 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
28240 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
28260 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
28270 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
28280 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
28290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
282a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
282b0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
282c0 61 72 79 20 44 61 74 61 20 7b 46 31 36 32 37 30  ary Data {F16270
282d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  }.**.** The foll
282e0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
282f0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
28300 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
28310 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
28320 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74  sociate meta-dat
28330 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
28340 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
28350 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
28360 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
28370 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
28380 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
28390 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
283a0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
283b0 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
283c0 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
283d0 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d  associated meta-
283e0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
283f0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
28400 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
28410 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
28420 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
28430 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
28440 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
28450 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
28460 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
28470 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
28480 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
28490 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63   meta-data assoc
284a0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
284b0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
284c0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
284d0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
284e0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
284f0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
28500 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
28510 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
28520 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
28530 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
28540 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
28550 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
28560 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
28570 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28580 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
28590 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
285a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
285b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
285c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
285d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
285e0 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61  e meta-data.** a
285f0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
28600 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
28610 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
28620 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
28630 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
28640 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
28650 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28660 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74  on..** If no met
28670 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  a-data has been 
28680 65 76 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f  ever been set fo
28690 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67  r the Nth.** arg
286a0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
286b0 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
286c0 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66   cooresponding f
286d0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
286e0 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64  r.** has changed
286f0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
28700 64 61 74 61 20 77 61 73 20 73 65 74 2c 20 74 68  data was set, th
28710 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
28720 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75  uxdata().** retu
28730 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
28740 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
28750 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28760 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
28770 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74  ves the meta-dat
28780 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
28790 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
287a0 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
287b0 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  -data for the N-
287c0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
287d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
287e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
287f0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
28800 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
28810 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
28820 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
28830 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
28840 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
28850 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49  destroyed. .** I
28860 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
28870 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
28880 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
28890 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  tor .** function
288a0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
288b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
288c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
288d0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
288e0 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68  eta-data when th
288f0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
28900 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
28910 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
28920 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
28930 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
28940 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
28950 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
28960 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
28970 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
28980 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
28990 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61  eta-data on.** a
289a0 6e 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ny parameter of 
289b0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
289c0 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
289d0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a  nly guarantee.**
289e0 20 69 73 20 74 68 61 74 20 74 68 65 20 64 65 73   is that the des
289f0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
28a00 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
28a10 65 20 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a  e metadata is.**
28a20 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
28a30 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
28a40 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72  a-data is preser
28a50 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
28a60 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
28a70 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
28a80 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
28a90 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
28aa0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
28ab0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
28ac0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
28ad0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
28ae0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
28af0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
28b00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
28b10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
28b20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
28b30 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
28b40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
28b50 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
28b60 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
28b70 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
28b80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
28ba0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
28bb0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
28bc0 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
28bd0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
28be0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
28bf0 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
28c00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
28c10 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
28c20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
28c30 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
28c40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
28c50 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b  * {F16274} The [
28c60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
28c70 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
28c80 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
28c90 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
28ca0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
28cb0 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
28cc0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
28cd0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
28ce0 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
28cf0 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36     C..**.** {F16
28d00 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  276} SQLite will
28d10 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
28d20 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
28d30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
28d40 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63  **          whic
28d50 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74  h is the metadat
28d60 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c  a pointer P foll
28d70 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a  owing a call to.
28d80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28d90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
28da0 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20  (C,N,P,D)] when 
28db0 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
28dc0 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20   hold.**        
28dd0 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a    the metadata..
28de0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53  **.** {F16277} S
28df0 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
28e00 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f  hold metadata fo
28e10 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  r an SQL functio
28e20 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  n parameter.**  
28e30 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65          when the
28e40 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70   value of that p
28e50 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
28e60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d  ..**.** {F16278}
28e70 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   When [sqlite3_s
28e80 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
28e90 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c  ,D)] is invoked,
28ea0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
28eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
28ec0 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72  alled for any pr
28ed0 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73  ior metadata ass
28ee0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
28ef0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
28f00 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
28f10 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74  xt C and paramet
28f20 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  er N..**.** {F16
28f30 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  279} SQLite will
28f40 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72   call destructor
28f50 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61  s for any metada
28f60 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67  ta it is holding
28f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
28f80 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72  a particular [pr
28f90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28fa0 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a  ] S when either.
28fb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28fc0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f  ite3_reset(S)] o
28fd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
28fe0 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
28ff0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
29000 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
29010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29020 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
29030 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
29040 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
29050 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
29060 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
29070 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
29080 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
29090 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
290a0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
290b0 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a  avior {F10280}.*
290c0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
290d0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72  pecial value for
290e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
290f0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
29100 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
29110 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
29120 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
29130 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29140 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
29150 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
29160 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
29170 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
29180 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
29190 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
291a0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
291b0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
291c0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
291d0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
291e0 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45    The .** SQLITE
291f0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
29200 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29210 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
29220 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
29230 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
29240 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
29250 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
29260 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
29270 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
29280 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
29290 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
292a0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
292b0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
292c0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
292d0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
292e0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
292f0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
29300 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
29310 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
29320 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
29330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
29340 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
29350 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
29360 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
29370 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
29380 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
29390 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
293a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
293b0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
293c0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
293d0 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d  unction {F16400}
293e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
293f0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
29400 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
29410 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
29420 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
29430 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
29440 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
29450 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
29460 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29470 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29480 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29490 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
294a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
294b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
294c0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
294d0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
294e0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
294f0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
29500 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69  te3_bind_*] fami
29510 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20  ly of functions 
29520 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20  used.** to bind 
29530 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
29540 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
29550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
29560 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
29570 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
29580 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
29590 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e  3_bind_* documen
295a0 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61  tation] for.** a
295b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
295c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
295d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
295e0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
295f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
29600 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
29610 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
29620 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29630 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
29640 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
29650 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
29660 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
29670 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
29680 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
29690 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
296a0 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20   parameter. .** 
296b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
296c0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
296d0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
296e0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
296f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
29700 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29710 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
29720 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
29730 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
29740 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
29750 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
29760 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
29770 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
29780 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29790 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
297a0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
297b0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
297c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
297d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
297e0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
297f0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
29800 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
29810 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
29820 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
29830 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29850 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
29860 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
29870 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
29880 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
29890 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
298a0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
298b0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
298c0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
298d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
298e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
298f0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
29900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29910 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
29920 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
29930 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69  ssage.  SQLite i
29940 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
29950 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
29960 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
29970 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
29980 29 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74  ) as UTF8. SQLit
29990 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
299a0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
299b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
299c0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31  rror16() as UTF1
299d0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
299e0 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74  yte order.  If t
299f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29a00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
29a10 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
29a20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
29a30 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
29a40 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
29a50 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
29a60 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
29a70 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
29a80 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
29a90 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
29aa0 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20  ** If the third 
29ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29ad0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
29ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29af0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
29b00 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
29b10 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
29b20 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
29b30 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
29b40 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29b50 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
29b60 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  sage..** The sql
29b70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29b80 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
29b90 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29ba0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
29bb0 65 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65  e a copy private
29bc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
29bd0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
29be0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
29bf0 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
29c00 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
29c10 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
29c20 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
29c30 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
29c40 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
29c50 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20  ut harm..** The 
29c60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29c70 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
29c80 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
29c90 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
29ca0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
29cb0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
29cc0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
29cd0 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66  unction.  By def
29ce0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
29cf0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
29d00 45 5f 45 52 52 4f 52 2e 20 0a 2a 2a 0a 2a 2a 20  E_ERROR. .**.** 
29d10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29d20 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
29d30 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
29d40 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20  ite.** to throw 
29d50 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  an error indicat
29d60 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
29d70 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
29d80 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65  long.** to repre
29d90 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  sent.  The sqlit
29da0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
29db0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63  ) interface.** c
29dc0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
29dd0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
29de0 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  on indicating th
29df0 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f  at the a.** memo
29e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
29e10 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
29e20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
29e30 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
29e40 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
29e50 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
29e60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29e70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29e80 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
29e90 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
29ea0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
29eb0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
29ec0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
29ed0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
29ee0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
29ef0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
29f00 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
29f10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29f20 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
29f30 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29f40 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
29f50 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
29f60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
29f70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29f80 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
29f90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
29fa0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29fc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29fd0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
29fe0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
29ff0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
2a000 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a010 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65  16(), .** sqlite
2a020 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2a030 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2a040 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2a050 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2a060 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2a070 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2a080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a090 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2a0a0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2a0b0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2a0c0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2a0d0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2a0e0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2a0f0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2a100 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2a110 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2a120 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  ively..** SQLite
2a130 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
2a140 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
2a150 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
2a160 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
2a170 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
2a180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a190 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2a1a0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
2a1b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2a1c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a1d0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2a1e0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2a1f0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2a200 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2a210 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a220 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  r .** through th
2a230 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2a240 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
2a250 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2a260 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2a270 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2a280 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2a290 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2a2a0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2a2b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2a2c0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2a2d0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2a2e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2a2f0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2a300 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a310 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2a320 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2a330 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2a340 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2a350 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2a360 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2a370 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2a380 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
2a390 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2a3a0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
2a3b0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
2a3c0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2a3d0 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20  he text or blob 
2a3e0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
2a3f0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
2a400 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2a410 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
2a420 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2a430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a440 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2a450 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2a460 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2a470 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2a480 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
2a490 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2a4a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2a4b0 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72  e text or blob r
2a4c0 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e  esult is constan
2a4d0 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64  t space and.** d
2a4e0 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65  oes not copy the
2a4f0 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61   space or call a
2a500 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
2a510 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2a520 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2a530 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2a540 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2a550 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2a560 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2a570 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2a580 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2a590 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2a5a0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2a5b0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2a5c0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2a5d0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2a5e0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2a5f0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2a600 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2a610 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2a620 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2a630 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a640 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2a650 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2a660 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2a670 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a680 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a690 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
2a6a0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a6b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a6c0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
2a6d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a6e0 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
2a6f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a700 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2a710 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a720 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2a730 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69  ** so that [sqli
2a740 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
2a750 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
2a760 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
2a770 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
2a780 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
2a790 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2a7a0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
2a7b0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70  ut harm..** A [p
2a7c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a7d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
2a7e0 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
2a7f0 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
2a800 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a810 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a820 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
2a830 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
2a840 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2a850 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
2a860 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
2a870 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2a880 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
2a890 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
2a8a0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
2a8b0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a  fferent thread .
2a8c0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
2a8d0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2a8e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a8f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
2a900 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65   recieved.** the
2a910 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2a920 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
2a930 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2a940 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
2a950 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2a960 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61  F16403} The defa
2a970 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ult return value
2a980 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75   from any SQL fu
2a990 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a  nction is NULL..
2a9a0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54  **.** {F16406} T
2a9b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2a9c0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2a9d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2a9e0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2a9f0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2aa00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2aa10 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61 74  o be a blob that
2aa20 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20   is N bytes.**  
2aa30 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74          in lengt
2aa40 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65  h and with conte
2aa50 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  nt pointed to by
2aa60 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30   V..**.** {F1640
2aa70 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2aa80 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c  result_double(C,
2aa90 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2aaa0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2aab0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2aac0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2aad0 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74   to be the float
2aae0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2aaf0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32  V..**.** {F16412
2ab00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2ab10 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c  esult_error(C,V,
2ab20 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
2ab30 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2ab40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2ab50 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2ab60 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
2ab70 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
2ab80 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
2ab90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
2aba0 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f 72 20  nd a UTF8 error 
2abb0 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66  message copied f
2abc0 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a  rom V up to the.
2abd0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
2abe0 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75  t zero byte or u
2abf0 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65  ntil N bytes are
2ac00 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
2ac10 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2ac20 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  16415} The [sqli
2ac30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ac40 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  16(C,V,N)] inter
2ac50 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2ac60 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
2ac70 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
2ac80 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2ac90 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2aca0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
2acb0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
2acc0 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 31  RROR] and a UTF1
2acd0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2ace0 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  der error messag
2acf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2ad00 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
2ad10 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2ad20 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75   terminator or u
2ad30 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20  ntil N bytes.** 
2ad40 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61           are rea
2ad50 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
2ad60 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
2ad70 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2ad80 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
2ad90 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63  big(C)] interfac
2ada0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2adb0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2adc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
2add0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2ade0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
2adf0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
2ae00 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2ae10 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61  TOOBIG] and an a
2ae20 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
2ae30 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2ae40 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71  {F16421} The [sq
2ae50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ae60 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74  or_nomem(C)] int
2ae70 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2ae80 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
2ae90 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
2aea0 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
2aeb0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
2aec0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
2aed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2aee0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20  LITE_NOMEM] and 
2aef0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
2af00 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2af10 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65  .** {F16424} The
2af20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2af30 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29  _error_code(C,E)
2af40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2af50 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
2af60 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
2af70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2af80 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
2af90 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
2afa0 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20   code E..**     
2afb0 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d       The error m
2afc0 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75  essage text is u
2afd0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
2afe0 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71  {F16427} The [sq
2aff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2b000 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
2b010 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2b020 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2b030 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2b040 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32  n C to be the 32
2b050 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
2b060 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ue V..**.** {F16
2b070 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  430} The [sqlite
2b080 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43  3_result_int64(C
2b090 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
2b0a0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2b0b0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2b0c0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2b0d0 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  C to be the 64-b
2b0e0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
2b0f0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33   V..**.** {F1643
2b100 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2b110 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20  result_null(C)] 
2b120 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2b130 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2b140 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2b150 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2b160 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  be NULL..**.** {
2b170 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c  F16436} The [sql
2b180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b190 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2b1a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2b1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2b1c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2b1d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2b1e0 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  e UTF8 string.**
2b1f0 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
2b200 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2b210 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e   zero or until N
2b220 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
2b230 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20  if N.**         
2b240 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
2b250 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65  .** {F16439} The
2b260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2b270 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
2b280 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2b290 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2b2a0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2b2b0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2b2c0 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6e  o be the UTF16 n
2b2d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b2e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2b2f0 69 6e 67 20 20 56 20 75 70 20 74 68 72 6f 75 67  ing  V up throug
2b300 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2b310 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
2b320 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a  s are read if N.
2b330 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
2b340 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2b350 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16442} The [sql
2b360 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b370 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
2b380 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2b390 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2b3a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2b3b0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2b3c0 65 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d  e the UTF16 big-
2b3d0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2b3e0 20 20 20 73 74 72 69 6e 67 20 20 56 20 75 70 20     string  V up 
2b3f0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2b400 74 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20  t zero or until 
2b410 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
2b420 20 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20   if N.**        
2b430 20 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a    is positive..*
2b440 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68  *.** {F16445} Th
2b450 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2b460 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
2b470 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
2b480 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2b490 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2b4a0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2b4b0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31  C to be the UTF1
2b4c0 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
2b4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2b4e0 6e 67 20 20 56 20 75 70 20 74 68 72 6f 75 67 68  ng  V up through
2b4f0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2b500 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2b510 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a   are read if N.*
2b520 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f  *          is po
2b530 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2b540 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
2b550 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2b560 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
2b570 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2b580 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2b590 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2b5a0 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f  n C to be [unpro
2b5b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b5c0 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20  alue].**        
2b5d0 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a    object V..**.*
2b5e0 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20 5b  * {F16451} The [
2b5f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2b600 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e  eroblob(C,N)] in
2b610 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2b620 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2b630 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2b640 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2b650 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20   an N-byte blob 
2b660 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a  of all zeros..**
2b670 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68 65  .** {F16454} The
2b680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2b690 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73  _error()] and [s
2b6a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b6b0 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ror16()].**     
2b6c0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
2b6d0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
2b6e0 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61  heir error messa
2b6f0 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72  ge strings befor
2b700 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2b710 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  turning..**.** {
2b720 46 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44  F16457} If the D
2b730 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
2b740 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2b750 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
2b760 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2b770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2b780 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
2b790 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
2b7a0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2b7b0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2b7c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2b7d0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
2b7e0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
2b7f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2b800 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2b810 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
2b820 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
2b830 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20  _STATIC].**     
2b840 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73       then no des
2b850 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20  tructor is ever 
2b860 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f  called on the po
2b870 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69  inter V and SQLi
2b880 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2b890 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73  ssumes that V is
2b8a0 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   immutable..**.*
2b8b0 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74 68  * {F16460} If th
2b8c0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
2b8d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2b8e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2b8f0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2b900 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2b910 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2b920 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
2b930 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
2b940 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
2b950 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2b960 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
2b970 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
2b980 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2b990 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2b9a0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74  e(C,V,N,D)] is t
2b9b0 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20  he constant.**  
2b9c0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2b9d0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20  TRANSIENT] then 
2b9e0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  the interfaces m
2b9f0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2ba00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2ba10 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20  ontent of V and 
2ba20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79  retains the copy
2ba30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d  ..**.** {F16463}
2ba40 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
2ba50 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
2ba60 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2ba70 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
2ba80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
2ba90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2baa0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
2bab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2bac0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
2bad0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2bae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2baf0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
2bb00 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2bb10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2bb20 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
2bb30 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20  ] is some value 
2bb40 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
2bb50 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74         the const
2bb60 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41  ants [SQLITE_STA
2bb70 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TIC] and [SQLITE
2bb80 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
2bb90 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51   .**          SQ
2bba0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2bbb0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2bbc0 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
2bbd0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
2bbe0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
2bbf0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2bc00 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
2bc10 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2bc20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
2bc30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2bc40 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2bc50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2bc60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2bc70 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
2bc80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
2bc90 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
2bca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bcb0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
2bcc0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2bcd0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2bce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2bcf0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2bd00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2bd10 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2bd20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bd30 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
2bd40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2bd50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bd60 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
2bd70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2bd80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2bd90 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
2bda0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bdb0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2bdc0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
2bdd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bde0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2bdf0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2be00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2be10 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2be20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2be30 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
2be40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2be50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2be60 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
2be70 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2be80 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
2be90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2bea0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2beb0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
2bec0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2bed0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2bee0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2bef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bf00 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2bf10 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2bf20 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2bf30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2bf40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2bf50 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2bf60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2bf70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2bf80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2bf90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2bfa0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
2bfb0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2bfc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
2bfd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2bfe0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2bff0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2c000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c010 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2c020 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2c030 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16600}.**.**
2c040 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2c050 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2c060 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2c070 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a  equences to the.
2c080 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  ** [sqlite3*] ha
2c090 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61  ndle specified a
2c0a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2c0b0 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ment. .**.** The
2c0c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
2c0d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2c0e0 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  nce is specified
2c0f0 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   as a UTF-8 stri
2c100 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
2c110 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c120 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
2c130 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c140 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
2c150 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f  UTF-16 string fo
2c160 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2c170 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20  _collation16(). 
2c180 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
2c190 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
2c1a0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
2c1b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2c1c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
2c1d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
2c1e0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
2c1f0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
2c200 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
2c210 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
2c220 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2c230 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2c240 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
2c250 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
2c260 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
2c270 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
2c280 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
2c290 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
2c2a0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2c2b0 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69  ian or UTF-16 bi
2c2c0 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  g-endian respect
2c2d0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68  ively. The.** th
2c2e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
2c2f0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
2c300 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2c310 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ] to indicate th
2c320 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  at.** the routin
2c330 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  e expects pointe
2c340 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72  rs to 16-bit wor
2c350 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67  d aligned string
2c360 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e  s.** of UTF16 in
2c370 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2c380 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f   order of the ho
2c390 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a  st computer..**.
2c3a0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
2c3b0 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
2c3c0 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
2c3d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2c3e0 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
2c3f0 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c  t.  If it is NUL
2c400 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
2c410 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
2c420 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2c430 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
2c440 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
2c450 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65   call it anymore
2c460 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20  )..** Each time 
2c470 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2c480 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
2c490 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
2c4a0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
2c4b0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
2c4c0 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
2c4d0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2c4e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
2c4f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2c500 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2c510 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2c520 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
2c530 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2c540 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
2c550 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2c560 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
2c570 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
2c580 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
2c590 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
2c5a0 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
2c5b0 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
2c5c0 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
2c5d0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
2c5e0 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
2c5f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2c600 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2c610 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
2c620 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
2c630 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63  {END} The applic
2c640 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
2c650 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
2c660 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
2c670 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
2c680 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a  or positive if.*
2c690 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  * the first stri
2c6a0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
2c6b0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
2c6c0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
2c6d0 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e  econd.** string.
2c6e0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
2c6f0 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
2c700 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
2c710 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2c720 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
2c730 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c740 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61  lation().** exca
2c750 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
2c760 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
2c770 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
2c780 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
2c790 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
2c7a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2c7b0 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2c7c0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2c7d0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2c7e0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2c7f0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2c800 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2c810 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2c820 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c830 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2c840 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  ** Collations ar
2c850 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
2c860 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65  .** they are ove
2c870 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2c880 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
2c890 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
2c8a0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72   functions.** or
2c8b0 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   when the [sqlit
2c8c0 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
2c8d0 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75  ndle is closed u
2c8e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
2c8f0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ose()]..**.** IN
2c900 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2c910 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63 63 65  {F16603} A succe
2c920 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68  ssful call to th
2c930 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
2c940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c950 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
2c960 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,P,F,D)] interfa
2c970 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ce.**          r
2c980 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f  egisters functio
2c990 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61  n F as the compa
2c9a0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75  rison function u
2c9b0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  sed to.**       
2c9c0 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c     implement col
2c9d0 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74  lation X on [dat
2c9e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c9f0 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ] B for.**      
2ca00 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61      databases ha
2ca10 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e  ving encoding E.
2ca20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20  .**.** {F16604} 
2ca30 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e  SQLite understan
2ca40 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  ds the X paramet
2ca50 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
2ca60 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2ca70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2ca80 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20  ,X,E,P,F,D)] as 
2ca90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2caa0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
2cab0 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68  F-8 string in wh
2cac0 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f  ich case is igno
2cad0 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68  red for ASCII ch
2cae0 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20  aracters and.** 
2caf0 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e           is sign
2cb00 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d  ificant for non-
2cb10 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
2cb20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d  ..**.** {F16606}
2cb30 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c   Successive call
2cb40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2cb50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2cb60 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
2cb70 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
2cb80 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
2cb90 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45   for B, X, and E
2cba0 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72  , override prior
2cbb0 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
2cbc0 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64      of P, F, and
2cbd0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30   D..**.** {F1660
2cbe0 39 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  9} The destructo
2cbf0 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r D in [sqlite3_
2cc00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2cc10 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2cc20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
2cc30 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69   not NULL then i
2cc40 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  t is called with
2cc50 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
2cc60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2cc70 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2cc80 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62  ion is dropped b
2cc90 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  y SQLite..**.** 
2cca0 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61  {F16612} A colla
2ccb0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
2ccc0 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74   dropped when it
2ccd0 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   is overloaded..
2cce0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41  **.** {F16615} A
2ccf0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2cd00 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
2cd10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2cd20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
2cd30 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65          is close
2cd40 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2cd50 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
2cd60 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f   {F16618} The po
2cd70 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69  inter P in [sqli
2cd80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2cd90 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2cda0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
2cdb0 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f    is passed thro
2cdc0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
2cdd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2cde0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  e comparison.** 
2cdf0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
2ce00 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73  n F for all subs
2ce10 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2ce20 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b  ns of F..**.** {
2ce30 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74  F16621} A call t
2ce40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2ce50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
2ce60 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74  E,P,F)] is exact
2ce70 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ly.**          t
2ce80 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c  he same as a cal
2ce90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2cea0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2ceb0 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20  2()] with.**    
2cec0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70        the same p
2ced0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20  arameters and a 
2cee0 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e  NULL destructor.
2cef0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20  .**.** {F16624} 
2cf00 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c  Following a [sql
2cf10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2cf20 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2cf30 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,F,D)],.**      
2cf40 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20      SQLite uses 
2cf50 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
2cf60 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
2cf70 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f  l text compariso
2cf80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  n.**          op
2cf90 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74  erations on [dat
2cfa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cfb0 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
2cfc0 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
2cfd0 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
2cfe0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
2cff0 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ame X..**.** {F1
2d000 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6627} The [sqlit
2d010 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2d020 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29  ion16(B,X,E,P,F)
2d030 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  ] works the same
2d040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
2d050 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d060 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
2d070 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61  P,F)] except tha
2d080 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
2d090 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65    collation name
2d0a0 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64   X is understood
2d0b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
2d0c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
2d0d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74  **          inst
2d0e0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
2d0f0 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65  .** {F16630} Whe
2d100 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61  n multiple compa
2d110 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  rison functions 
2d120 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f  are available fo
2d130 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  r the same.**   
2d140 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
2d150 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74   sequence, SQLit
2d160 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e  e chooses the on
2d170 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63  e whose text enc
2d180 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  oding.**        
2d190 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c    requires the l
2d1a0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63  east amount of c
2d1b0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74  onversion from t
2d1c0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  he default.**   
2d1d0 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f         text enco
2d1e0 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ding of the data
2d1f0 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  base..*/.int sql
2d200 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2d210 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2d220 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2d230 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2d240 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2d250 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2d260 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2d270 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2d280 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2d290 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2d2a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2d2b0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2d2c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2d2d0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2d2e0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2d2f0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2d300 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2d310 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2d320 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2d330 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2d340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2d350 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2d360 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2d370 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2d380 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2d390 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2d3a0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2d3b0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2d3c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2d3d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2d3e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
2d3f0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
2d400 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a  backs {F16700}.*
2d410 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61  *.** To avoid ha
2d420 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
2d430 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
2d440 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
2d450 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
2d460 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
2d470 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
2d480 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
2d490 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
2d4a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
2d4b0 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  dle to be called
2d4c0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2d4d0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2d4e0 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20   sequence is.** 
2d4f0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2d500 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
2d510 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
2d520 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2d530 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d540 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
2d550 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
2d560 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
2d570 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
2d580 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
2d590 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
2d5a0 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d   UTF-8. {F16703}
2d5b0 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
2d5c0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2d5d0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61   is used, the na
2d5e0 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  mes.** are passe
2d5f0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
2d600 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
2d610 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c  te order. A call
2d620 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75   to either.** fu
2d630 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
2d640 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
2d650 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
2d660 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
2d670 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
2d680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
2d690 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
2d6a0 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
2d6b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2d6c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2d6d0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
2d6e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2d6f0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
2d700 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2d710 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
2d720 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65 20  ** handle.  The 
2d730 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2d740 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2d750 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
2d760 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2d770 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2d780 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
2d790 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62   most.** desirab
2d7a0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
2d7b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2d7c0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
2d7d0 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72  red..** The four
2d7e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2d7f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
2d800 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
2d810 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a  ation sequence..
2d820 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2d830 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
2d840 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
2d850 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
2d860 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2d870 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d880 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
2d890 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2d8a0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
2d8b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d8c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
2d8d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2d8e0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d  :.**.** {F16702}
2d8f0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
2d900 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2d910 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2d920 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20  D,P,F)].**      
2d930 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2d940 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d950 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65  16(D,P,F)] cause
2d960 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
2d970 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d980 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76  ection] D to inv
2d990 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77  oke callback F w
2d9a0 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20  ith first.**    
2d9b0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
2d9c0 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65  P whenever it ne
2d9d0 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e  eds a comparison
2d9e0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a   function for a.
2d9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
2da00 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74  ating sequence t
2da10 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
2da20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a  know about..**.*
2da30 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68 20  * {F16704} Each 
2da40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2da50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
2da60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2da70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2da80 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2da90 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76  n_needed16()] ov
2daa0 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c  errides the call
2dab0 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a  back registered.
2dac0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
2dad0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2dae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79  e connection] by
2daf0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
2db00 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
2db10 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a     interface..**
2db20 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68 65  .** {F16706} The
2db30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71   name of the req
2db40 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67  uested collating
2db50 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64   function passed
2db60 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
2db70 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65      4th paramete
2db80 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
2db90 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66  k is in UTF-8 if
2dba0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
2dbb0 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65            was re
2dbc0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
2dbd0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2dbe0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a  n_needed()] and.
2dbf0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
2dc00 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  n UTF-16 native 
2dc10 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68  byte order if th
2dc20 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a  e callback was.*
2dc30 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
2dc40 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
2dc50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2dc60 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  eeded16()]..**.*
2dc70 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  * .*/.int sqlite
2dc80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2dc90 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
2dca0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
2dcb0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2dcc0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2dcd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
2dce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2dcf0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2dd00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2dd10 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
2dd20 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2dd30 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2dd40 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
2dd50 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2dd60 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
2dd70 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
2dd80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
2dd90 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
2dda0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
2ddb0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
2ddc0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2ddd0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2dde0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2ddf0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2de00 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2de10 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2de20 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
2de30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2de40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2de50 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
2de60 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
2de70 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
2de80 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
2de90 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2dea0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
2deb0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
2dec0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
2ded0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
2dee0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
2def0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
2df00 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
2df10 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
2df20 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
2df30 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
2df40 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
2df50 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2df60 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2df70 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2df80 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2df90 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2dfa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2dfb0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
2dfc0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2dfd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2dfe0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2dff0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2e000 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2e010 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
2e020 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
2e030 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 75  ** CAPI3REF:  Su
2e040 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
2e050 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
2e060 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10530}.**.** 
2e070 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2e080 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  p() function.** 
2e090 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
2e0a0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
2e0b0 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
2e0c0 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
2e0d0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2e0e0 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
2e0f0 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
2e100 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
2e110 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2e120 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2e130 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2e140 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69  s with .** milli
2e150 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
2e160 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
2e170 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
2e180 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20  unded up to .** 
2e190 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
2e1a0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
2e1b0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2e1c0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2e1d0 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66   .** requested f
2e1e0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
2e1f0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
2e200 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rned..**.** SQLi
2e210 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2e220 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2e230 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2e240 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2e250 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2e260 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2e270 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ct..**.** INVARI
2e280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
2e290 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  533} The [sqlite
2e2a0 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
2e2b0 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68  rface invokes th
2e2c0 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20  e xSleep.**     
2e2d0 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74       method of t
2e2e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2e2f0 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20  te3_vfs|VFS] in 
2e300 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  order to.**     
2e310 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65       suspend exe
2e320 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
2e330 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72  rrent thread for
2e340 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20   at least.**    
2e350 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63        M millisec
2e360 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  onds..**.** {F10
2e370 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  536} The [sqlite
2e380 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
2e390 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2e3a0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
2e3b0 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63          millisec
2e3c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
2e3d0 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64  tually requested
2e3e0 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   of the operatin
2e3f0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79  g.**          sy
2e400 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68  stem, which migh
2e410 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
2e420 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d   the parameter M
2e430 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e440 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
2e450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e  .** CAPI3REF:  N
2e460 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2e470 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2e480 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31  ary Files {F1031
2e490 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0}.**.** If this
2e4a0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2e4b0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2e4c0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2e4d0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2e4e0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2e4f0 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29  a.ka. directory)
2e500 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
2e510 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
2e520 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
2e530 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
2e540 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
2e550 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61  .  If this varia
2e560 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70  ble.** is NULL p
2e570 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2e580 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 72 63  ite does a searc
2e590 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2e5a0 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  iate temporary.*
2e5b0 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  * file directory
2e5c0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2e5d0 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79  t safe to modify
2e5e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f   this variable o
2e5f0 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 20 63  nce a database c
2e600 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73  onnection.** has
2e610 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
2e620 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
2e630 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2e640 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
2e650 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
2e660 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
2e670 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
2e680 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2e690 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
2e6a0 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
2e6b0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2e6c0 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
2e6d0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
2e6e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
2e6f0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
2e700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
2e710 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
2e720 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e  e Database Is In
2e730 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
2e740 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a  e {F12930}.**.**
2e750 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
2e760 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
2e770 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
2e780 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
2e790 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
2e7a0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
2e7b0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
2e7c0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
2e7d0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
2e7e0 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f  tively.   Autoco
2e7f0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a  mmit mode is on.
2e800 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ** by default.  
2e810 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2e820 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
2e830 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
2e840 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  nt..** Autocommi
2e850 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e 61 62  t mode is reenab
2e860 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2e870 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2e880 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2e890 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2e8a0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2e8b0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2e8c0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2e8d0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  ** transactions 
2e8e0 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
2e8f0 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
2e900 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
2e910 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d   .** [SQLITE_NOM
2e920 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
2e930 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
2e940 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
2e950 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
2e960 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
2e970 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
2e980 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
2e990 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
2e9a0 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20 61   out if SQLite a
2e9b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2e9c0 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
2e9d0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
2e9e0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
2e9f0 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
2ea00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
2ea10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
2ea20 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  931} The [sqlite
2ea30 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2ea40 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
2ea50 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
2ea60 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  or.**          z
2ea70 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61  ero if the [data
2ea80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ea90 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20   D is or is not 
2eaa0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a  in autocommit.**
2eab0 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20            mode, 
2eac0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2ead0 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74  .** {F12932} Aut
2eae0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2eaf0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2eb00 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75  *.** {F12933} Au
2eb10 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2eb20 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73   disabled by a s
2eb30 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e  uccessful [BEGIN
2eb40 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  ] statement..**.
2eb50 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f  ** {F12934} Auto
2eb60 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65  commit mode is e
2eb70 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  nabled by a succ
2eb80 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20  essful [COMMIT] 
2eb90 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a  or [ROLLBACK].**
2eba0 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
2ebb0 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c  ent..** .**.** L
2ebc0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a  IMITATIONS:.***.
2ebd0 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66 20 61  ** {U12936} If a
2ebe0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
2ebf0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
2ec00 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
2ec10 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  he database.**  
2ec20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69          connecti
2ec30 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
2ec40 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
2ec50 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
2ec60 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  n value.**      
2ec70 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64      is undefined
2ec80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ec90 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2eca0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
2ecb0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e  * CAPI3REF:  Fin
2ecc0 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48  d The Database H
2ecd0 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61  andle Of A Prepa
2ece0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  red Statement {F
2ecf0 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13120}.**.** The
2ed00 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2ed10 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  le interface.** 
2ed20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c  returns the [sql
2ed30 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20  ite3*] database 
2ed40 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20  handle to which 
2ed50 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  a.** [prepared s
2ed60 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
2ed70 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61  s..** The databa
2ed80 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e  se handle return
2ed90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
2eda0 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68  _handle.** is th
2edb0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2edc0 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a  handle that was.
2edd0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 67  ** the first arg
2ede0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
2edf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ee00 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2ee10 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  nts.** that was 
2ee20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 74  used to create t
2ee30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
2ee40 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2ee50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2ee60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33  S:.**.** {F13123
2ee70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  } The [sqlite3_d
2ee80 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74  b_handle(S)] int
2ee90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2eea0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
2eeb0 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74       to the [dat
2eec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2eed0 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
2eee0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  h.**          [p
2eef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ef00 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] S..*/.sqlite3
2ef10 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
2ef20 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
2ef30 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *);.../*.** CAPI
2ef40 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2ef50 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2ef60 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2ef70 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12950}.**.** 
2ef80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
2ef90 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
2efa0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2efb0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2efc0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2efd0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2efe0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
2eff0 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
2f000 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2f010 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2f020 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2f030 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2f040 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2f050 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2f060 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
2f070 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2f080 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2f090 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2f0a0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2f0b0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2f0c0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2f0d0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
2f0e0 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
2f0f0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2f100 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2f110 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2f120 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2f130 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2f140 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2f150 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
2f160 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
2f170 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
2f180 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  h.** to the call
2f190 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61  back.  If the ca
2f1a0 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
2f1b0 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
2f1c0 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e   .** returns non
2f1d0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
2f1e0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
2f1f0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
2f200 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
2f210 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
2f220 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
2f230 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
2f240 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
2f250 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
2f260 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
2f270 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  rned..**.** Regi
2f280 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2f290 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2f2a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2f2b0 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72  *.** For the pur
2f2c0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
2f2d0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
2f2e0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
2f2f0 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64   been .** rolled
2f300 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2f310 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2f320 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2f330 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2f340 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2f350 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2f360 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2f370 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
2f380 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2f390 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2f3a0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2f3b0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2f3c0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2f3d0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2f3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f3f0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2f400 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2f410 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2f420 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2f430 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
2f440 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
2f450 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
2f460 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
2f470 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
2f480 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
2f490 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  todo>.**.** Thes
2f4a0 65 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74  e are experiment
2f4b0 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e  al interfaces an
2f4c0 64 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  d are subject to
2f4d0 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49   change..**.** I
2f4e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2f4f0 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20 5b 73   {F12951} The [s
2f500 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2f510 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
2f520 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74  face registers t
2f530 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2f540 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2f550 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
2f560 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
2f570 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
2f580 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74        a transact
2f590 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b  ion commits on [
2f5a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f5b0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
2f5c0 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69  12952} The [sqli
2f5d0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2f5e0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
2f5f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a  e returns the P.
2f600 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
2f610 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
2f620 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68  evious call with
2f630 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20   the same .**   
2f640 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
2f650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20   connection ] D 
2f660 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65  , or NULL on the
2f670 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20   first call.**  
2f680 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61          for a pa
2f690 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61  rticular [databa
2f6a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2f6b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d  ..**.** {F12953}
2f6c0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
2f6d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2f6e0 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  ok()] overwrites
2f6f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
2f700 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2f710 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61  ered by prior ca
2f720 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  lls..**.** {F129
2f730 35 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67  54} If the F arg
2f740 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
2f750 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
2f760 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
2f770 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2f780 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
2f790 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
2f7a0 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c  lled and no call
2f7b0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
2f7c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2f7d0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63   a transaction c
2f7e0 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ommits..**.** {F
2f7f0 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f  12955} If the co
2f800 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65  mmit callback re
2f810 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74  turns non-zero t
2f820 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
2f830 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  s.**          co
2f840 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2f850 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  ollback..**.** {
2f860 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c  F12961} The [sql
2f870 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2f880 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
2f890 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74  face registers t
2f8a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2f8b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2f8c0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
2f8d0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
2f8e0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
2f8f0 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74        a transact
2f900 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f  ion rolls back o
2f910 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
2f920 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2f930 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {F12962} The [s
2f940 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2f950 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
2f960 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f970 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
2f980 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
2f990 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2f9a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
2f9b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2f9c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f9d0 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
2f9e0 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
2f9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
2fa00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
2fa10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fa20 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
2fa30 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2963} Each call 
2fa40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  to [sqlite3_roll
2fa50 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  back_hook()] ove
2fa60 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
2fa70 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
2fa80 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
2fa90 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
2faa0 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20 74 68  * {F12964} If th
2fab0 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
2fac0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2fad0 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
2fae0 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
2faf0 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c     then the roll
2fb00 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  back hook callba
2fb10 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20  ck is cancelled 
2fb20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
2fb30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
2fb40 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
2fb50 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
2fb60 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  back..*/.void *s
2fb70 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2fb80 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
2fb90 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
2fba0 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
2fbb0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2fbc0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
2fbd0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
2fbe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fbf0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
2fc00 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2fc10 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a  lbacks {F12970}.
2fc20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2fc30 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
2fc40 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67  interface.** reg
2fc50 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2fc60 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  k function with 
2fc70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2fc80 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
2fc90 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
2fca0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2fcb0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2fcc0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2fcd0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2fce0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
2fcf0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2fd00 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2fd10 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
2fd20 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  on for the same 
2fd30 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
2fd40 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2fd50 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
2fd60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2fd70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2fd80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
2fd90 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a   invoke when a .
2fda0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
2fdb0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
2fdc0 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20  eleted. .** The 
2fdd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2fde0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2fdf0 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
2fe00 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2fe10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
2fe20 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
2fe30 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
2fe40 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ck .** argument 
2fe50 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2fe60 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
2fe70 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53  TE_DELETE] or [S
2fe80 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a  QLITE_UPDATE],.*
2fe90 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
2fea0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
2feb0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
2fec0 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
2fed0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
2fee0 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
2fef0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2ff00 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
2ff10 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
2ff20 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
2ff30 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
2ff40 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
2ff50 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54  fected row..** T
2ff60 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
2ff70 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
2ff80 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
2ff90 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74  the row..** In t
2ffa0 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
2ffb0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
2ffc0 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
2ffd0 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
2ffe0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
2fff0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
30000 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
30010 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
30020 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
30030 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
30040 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
30050 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
30060 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
30070 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
30080 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
30090 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
300a0 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
300b0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
300c0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
300d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  rned..**.** INVA
300e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
300f0 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  12971} The [sqli
30100 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
30110 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
30120 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
30130 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
30140 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
30150 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73  nvoked with firs
30160 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68  t parameter P wh
30170 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
30180 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69     a table row i
30190 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
301a0 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  rted, or deleted
301b0 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   on.**          
301c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
301d0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
301e0 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c  F12973} The [sql
301f0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30200 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
30210 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ce returns the v
30220 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
30230 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72   of P for the pr
30240 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74  evious call on t
30250 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
30260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
30270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
30280 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72  NULL for the fir
30290 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  st call..**.** {
302a0 46 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75  F12975} If the u
302b0 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
302c0 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65  ack F in [sqlite
302d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
302e0 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,P)].**        
302f0 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74    is NULL then t
30300 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c  he no update cal
30310 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e  lbacks are made.
30320 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20  .**.** {F12977} 
30330 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
30340 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
30350 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69  k(D,F,P)] overri
30360 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a  des prior calls.
30370 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
30380 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63  he same interfac
30390 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  e on the same [d
303a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
303b0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
303c0 32 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65  2979} The update
303d0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
303e0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
303f0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
30400 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  em.**          t
30410 61 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71  ables such as sq
30420 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
30430 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20  sqlite_sequence 
30440 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  are modified..**
30450 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65  .** {F12981} The
30460 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
30470 72 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20  r to the update 
30480 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20  callback .**    
30490 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20        is one of 
304a0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
304b0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
304c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
304d0 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  TE],.**         
304e0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
304f0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
30500 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
30510 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
30520 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ed..**.** {F1298
30530 33 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  3} The third and
30540 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
30550 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
30560 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
30570 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  rs.**          t
30580 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
30590 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
305a0 77 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61  which are the na
305b0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  mes of the.**   
305c0 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
305d0 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69  and table that i
305e0 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e  s being updated.
305f0 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68  ..** {F12985} Th
30600 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
30610 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30620 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
30630 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20  ow after.**     
30640 20 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20       the change 
30650 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20  occurs..*/.void 
30660 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
30670 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
30680 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
30690 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
306a0 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
306b0 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
306c0 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
306d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
306e0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
306f0 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
30700 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a  ache {F10330}.**
30710 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
30720 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
30730 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
30740 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
30750 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
30760 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
30770 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e  ures between con
30780 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  nections to the 
30790 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a  same database..*
307a0 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  * Sharing is ena
307b0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
307c0 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64  ment is true and
307d0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
307e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
307f0 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63  false..**.** Cac
30800 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
30810 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
30820 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74  ed.** for an ent
30830 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e  ire process. {EN
30840 44 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61  D} This is a cha
30850 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
30860 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a   version 3.5.0..
30870 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  ** In prior vers
30880 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20  ions of SQLite, 
30890 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65  sharing was.** e
308a0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
308b0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
308c0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
308d0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
308e0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
308f0 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
30900 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
30910 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
30920 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
30930 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
30940 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
30950 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
30960 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
30970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30980 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
30990 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
309a0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
309b0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
309c0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
309d0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
309e0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
309f0 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
30a00 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
30a10 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
30a20 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
30a30 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
30a40 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
30a50 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
30a60 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
30a70 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
30a80 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
30a90 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
30aa0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30ab0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
30ac0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a  hared cache was.
30ad0 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
30ae0 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
30af0 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
30b00 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
30b10 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  rned otherwise..
30b20 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63  **.** Shared cac
30b30 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
30b40 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
30b50 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
30b60 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
30b70 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
30b80 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
30b90 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
30ba0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
30bb0 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
30bc0 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
30bd0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
30be0 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33  TS:.** .** {F103
30bf0 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  31} A successful
30c00 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
30c10 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
30c20 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a  hared_cache(B)].
30c30 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
30c40 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
30c50 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20  le shared cache 
30c60 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62  mode for any sub
30c70 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20  sequently.**    
30c80 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64        created [d
30c90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30ca0 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20  on] in the same 
30cb0 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  process..**.** {
30cc0 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61  F10336} When sha
30cd0 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61  red cache is ena
30ce0 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
30cf0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
30d00 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
30d10 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61  interface will a
30d20 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
30d30 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  error..**.** {F1
30d40 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  0337} The [sqlit
30d50 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
30d60 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72  _cache(B)] inter
30d70 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
30d80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
30d90 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
30da0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
30db0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
30dc0 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
30dd0 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64   {F10339} Shared
30de0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
30df0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
30e00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
30e10 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
30e20 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
30e30 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70  API3REF:  Attemp
30e40 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
30e50 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a  emory {F17340}.*
30e60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30e70 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
30e80 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
30e90 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20  mpts to.** free 
30ea0 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
30eb0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
30ec0 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
30ed0 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tial memory.** a
30ee0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
30ef0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
30f00 6c 61 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  labrary. {END}  
30f10 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74  Memory used.** t
30f20 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
30f30 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
30f40 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
30f50 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a   an example of.*
30f60 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  * non-essential 
30f70 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33  memory.  Sqlite3
30f80 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
30f90 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  ) returns.** the
30fa0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
30fb0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
30fc0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
30fd0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20  more or less.** 
30fe0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
30ff0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  requested..**.**
31000 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31010 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20  ** {F17341} The 
31020 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
31030 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65  _memory(N)] inte
31040 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
31050 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  o.**          fr
31060 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
31070 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
31080 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
31090 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20  sential.**      
310a0 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63      memory alloc
310b0 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
310c0 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62 72  he database labr
310d0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ary..**.** {F163
310e0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
310f0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
31100 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20  N)] returns the 
31110 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
31120 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75     of bytes actu
31130 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
31140 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
31150 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  or less.**      
31160 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f      than the amo
31170 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
31180 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
31190 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
311a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
311b0 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69  EF:  Impose A Li
311c0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
311d0 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F17350}.**.** 
311e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
311f0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
31200 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65  terface.** place
31210 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
31220 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
31230 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
31240 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
31250 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ted.** by SQLite
31260 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  . If an internal
31270 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
31280 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61  equested .** tha
31290 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
312a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
312b0 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
312c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
312d0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  s.** invoked one
312e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
312f0 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
31300 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
31310 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
31320 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   made..**.** The
31330 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
31340 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
31350 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
31360 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
31370 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
31380 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
31390 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
313a0 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
313b0 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
313c0 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
313d0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
313e0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
313f0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
31400 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
31410 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
31420 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
31430 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
31440 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
31450 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
31460 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
31470 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
31480 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
31490 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
314a0 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
314b0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
314c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
314d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
314e0 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
314f0 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
31500 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31510 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20  it.  .** But if 
31520 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
31530 6d 69 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72  mit cannot honor
31540 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  ed, execution wi
31550 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
31560 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
31570 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
31580 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
31590 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
315a0 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
315b0 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
315c0 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
315d0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
315e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
315f0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
31600 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
31610 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
31620 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
31630 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
31640 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
31650 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
31660 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
31670 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
31680 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
31690 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
316a0 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
316b0 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
316c0 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
316d0 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
316e0 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
316f0 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
31700 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
31710 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31720 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
31730 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
31740 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
31750 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
31760 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
31770 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
31780 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
31790 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
317a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  TS:.**.** {F1635
317b0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
317c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
317d0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c  N)] interface pl
317e0 61 63 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69  aces a soft limi
317f0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  t.**          of
31800 20 4e 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20   N bytes on the 
31810 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
31820 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
31830 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20  e allocated.**  
31840 20 20 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73          using [s
31850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
31860 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
31870 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70  lloc()] at any p
31880 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  oint.**         
31890 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
318a0 7b 46 31 36 33 35 32 7d 20 49 66 20 61 20 63 61  {F16352} If a ca
318b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ll to [sqlite3_m
318c0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
318d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
318e0 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20  would.**        
318f0 20 20 63 61 75 73 65 20 74 68 65 20 74 6f 74 61    cause the tota
31900 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f  l amount of allo
31910 63 61 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20  cated memory to 
31920 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20  exceed the.**   
31930 20 20 20 20 20 20 20 73 6f 66 74 20 68 65 61 70         soft heap
31940 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71   limit, then [sq
31950 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
31960 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b  mory()] is invok
31970 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
31980 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20  n an attempt to 
31990 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72  reduce the memor
319a0 79 20 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f  y usage prior to
319b0 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20   proceeding.**  
319c0 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
319d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
319e0 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a  on attempt..**.*
319f0 2a 20 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73  * {F16353} Calls
31a00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
31a10 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
31a20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
31a30 61 74 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20  at trigger.**   
31a40 20 20 20 20 20 20 20 61 74 74 65 6d 70 74 73 20         attempts 
31a50 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79  to reduce memory
31a60 20 75 73 61 67 65 20 74 68 72 6f 75 67 68 20 74   usage through t
31a70 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
31a80 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
31a90 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75  echanism continu
31aa0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 61 74  e even if the at
31ab0 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20  tempt to reduce 
31ac0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
31ad0 20 20 20 75 73 61 67 65 20 69 73 20 75 6e 73 75     usage is unsu
31ae0 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20  ccessful..**.** 
31af0 7b 46 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74  {F16354} A negat
31b00 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
31b10 65 20 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c  e for N in a cal
31b20 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
31b30 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
31b40 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65  eap_limit(N)] me
31b50 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
31b60 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20  s no soft.**    
31b70 20 20 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74        heap limit
31b80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
31b90 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
31ba0 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20  will only be.** 
31bb0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20           called 
31bc0 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63  when memory is c
31bd0 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73  ompletely exhaus
31be0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ted..**.** {F163
31bf0 35 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  55} The default 
31c00 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
31c10 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
31c20 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
31c30 36 33 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20  6358} Each call 
31c40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  to [sqlite3_soft
31c50 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
31c60 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
31c70 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73            values
31c80 20 73 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f   set by all prio
31c90 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64  r calls..*/.void
31ca0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
31cb0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a  ap_limit(int);..
31cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31cd0 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
31ce0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
31cf0 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32   Of A Table {F12
31d00 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  850}.**.** This 
31d10 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72  routine.** retur
31d20 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f  ns meta-data abo
31d30 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
31d40 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
31d50 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  ic database.** t
31d60 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
31d70 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  using the connec
31d80 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73  tion handle pass
31d90 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
31da0 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67  function .** arg
31db0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
31dc0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
31dd0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
31de0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
31df0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
31e00 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e   to .** this fun
31e10 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e  ction. The secon
31e20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
31e30 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
31e40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
31e50 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
31e60 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74  "temp" or an att
31e70 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
31e80 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
31e90 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
31ea0 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74  e or NULL. If it
31eb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
31ec0 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
31ed0 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
31ee0 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
31ef0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
31f00 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20  me algorithm as 
31f10 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
31f20 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20  ine uses to .** 
31f30 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66  resolve unqualif
31f40 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65  ied table refere
31f50 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nces..**.** The 
31f60 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
31f70 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
31f80 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
31f90 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
31fa0 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f  olumn .** name o
31fb0 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  f the desired co
31fc0 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65  lumn, respective
31fd0 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74  ly. Neither of t
31fe0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
31ff0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
32000 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f  .**.** Meta info
32010 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72  rmation is retur
32020 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
32030 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
32040 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
32050 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20  .** the 5th and 
32060 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
32070 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
32080 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74  nction. Any of t
32090 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  hese .** argumen
320a0 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20  ts may be NULL, 
320b0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
320c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
320d0 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20  element of meta 
320e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
320f0 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a  is ommitted..**.
32100 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61  ** <pre>.** Para
32110 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74  meter     Output
32120 20 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72   Type      Descr
32130 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d  iption.** ------
32140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
32150 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
32160 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20  .**   5th       
32170 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20    const char*   
32180 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20     Data type.** 
32190 20 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f    6th         co
321a0 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e  nst char*      N
321b0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75  ame of the defau
321c0 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
321d0 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20  uence .**   7th 
321e0 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
321f0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
32200 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20   the column has 
32210 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  a NOT NULL const
32220 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20  raint.**   8th  
32230 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
32240 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
32250 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61  the column is pa
32260 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  rt of the PRIMAR
32270 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20  Y KEY.**   9th  
32280 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
32290 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
322a0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55  the column is AU
322b0 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c  TOINCREMENT.** <
322c0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  /pre>.**.**.** T
322d0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
322e0 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
322f0 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
32300 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20  eturned for the 
32310 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
32320 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
32330 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
32340 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
32350 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c  the next .** cal
32360 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20  l to any sqlite 
32370 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  API function..**
32380 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
32390 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
323a0 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74  tually a view, t
323b0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20  hen an error is 
323c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
323d0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
323e0 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
323f0 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
32400 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a  owid_" and an .*
32410 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  * INTEGER PRIMAR
32420 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73  Y KEY column has
32430 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
32440 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
32450 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70  the output .** p
32460 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
32470 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
32480 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
32490 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69  lumn. If there i
324a0 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
324b0 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20  ly declared IPK 
324c0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
324d0 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65   output paramete
324e0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a  rs are set as .*
324f0 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  * follows:.**.**
32500 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
32510 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
32520 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
32530 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
32540 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
32550 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
32560 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
32570 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
32580 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
32590 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
325a0 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
325b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
325c0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
325d0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
325e0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
325f0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
32600 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
32610 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
32620 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
32630 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53  t be found, an S
32640 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65  QLITE error code
32650 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
32660 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
32670 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65  e.** left in the
32680 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
32690 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
326a0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
326b0 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a  errmsg())..**.**
326c0 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c   This API is onl
326d0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
326e0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
326f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
32700 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
32710 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
32720 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
32730 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
32740 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
32750 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
32760 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
32770 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
32780 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
32790 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
327a0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
327b0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
327c0 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
327d0 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
327e0 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
327f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
32800 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
32810 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
32820 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
32830 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
32840 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
32850 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
32860 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
32870 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
32880 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
32890 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
328a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
328b0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
328c0 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
328d0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
328e0 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
328f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
32900 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
32910 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
32920 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
32930 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
32940 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
32950 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
32960 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
32970 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
32980 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
32990 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
329a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
329b0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b  d An Extension {
329c0 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12600}.**.** {F
329d0 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74  12601} The sqlit
329e0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
329f0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  n() interface.**
32a00 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
32a10 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  d an SQLite exte
32a20 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
32a30 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
32a40 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46  ile.** zFile. {F
32a50 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79  12602} The entry
32a60 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
32a70 20 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f 63 20   {F12603} zProc 
32a80 6d 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77  may be 0.** in w
32a90 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
32aa0 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
32ab0 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a  point defaults.*
32ac0 2a 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  * to "sqlite3_ex
32ad0 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
32ae0 2a 0a 2a 2a 20 7b 46 31 32 36 30 34 7d 20 54 68  *.** {F12604} Th
32af0 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
32b00 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
32b10 66 61 63 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65  face shall.** re
32b20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
32b30 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
32b40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
32b50 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
32b60 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46   wrong..**.** {F
32b70 31 32 36 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20  12605}.** If an 
32b80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
32b90 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
32ba0 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20   0, then the.** 
32bb0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
32bc0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
32bd0 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
32be0 20 74 6f 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d   to fill *pzErrM
32bf0 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f  sg with .** erro
32c00 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
32c10 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20  tored in memory 
32c20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32c30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
32c40 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20  ..** {END}  The 
32c50 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
32c60 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
32c70 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63  s memory.** by c
32c80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
32c90 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  free()]..**.** {
32ca0 46 31 32 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e  F12606}.** Exten
32cb0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
32cc0 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
32cd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
32ce0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
32cf0 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  n()].** prior to
32d00 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
32d10 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69  I or an error wi
32d20 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
32d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
32d40 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
32d50 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32d60 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
32d70 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
32d80 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
32d90 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
32da0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
32db0 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
32dc0 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
32dd0 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
32de0 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
32df0 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
32e00 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
32e10 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
32e20 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
32e30 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
32e40 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
32e50 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
32e60 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
32e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32e80 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
32e90 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
32ea0 6f 61 64 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a  oading {F12620}.
32eb0 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
32ec0 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
32ed0 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
32ee0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
32ef0 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
32f00 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
32f10 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
32f20 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
32f30 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
32f40 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
32f50 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
32f60 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
32f70 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
32f80 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20  owing.** API is 
32f90 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
32fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
32fb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
32fc0 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
32fd0 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46 31 32 36 32  .** off.  {F1262
32fe0 32 7d 20 49 74 20 69 73 20 6f 66 66 20 62 79 20  2} It is off by 
32ff0 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53  default. {END} S
33000 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e  ee ticket #1863.
33010 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20  .**.** {F12621} 
33020 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
33030 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
33040 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
33050 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  .** with onoff==
33060 31 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  1 to turn extens
33070 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a  ion loading on.*
33080 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  * and call it wi
33090 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
330a0 75 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20  urn it back off 
330b0 61 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a  again. {END}.*/.
330c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
330d0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
330e0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
330f0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
33100 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65  * CAPI3REF: Make
33110 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f   Arrangements To
33120 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
33130 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
33140 20 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12640}.**.** 
33150 7b 46 31 32 36 34 31 7d 20 54 68 69 73 20 66 75  {F12641} This fu
33160 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74  nction.** regist
33170 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
33180 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
33190 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
331a0 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  ly invoked.** wh
331b0 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74  enever a new dat
331c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
331d0 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67   is opened using
331e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
331f0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
33200 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
33210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
33220 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
33230 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
33240 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
33250 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
33260 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
33270 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
33280 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
33290 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
332a0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
332b0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64  .** to all new d
332c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
332d0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ons..**.** {F126
332e0 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78  42} Duplicate ex
332f0 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
33300 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
33310 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
33320 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
33330 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
33340 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
33350 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ess..**.** {F126
33360 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
33370 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
33380 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
33390 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
333a0 2a 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e  * that is obtain
333b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d  ed from sqlite_m
333c0 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49  alloc(). {END} I
333d0 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f  f you run a memo
333e0 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b  ry leak.** check
333f0 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72  er on your progr
33400 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74  am and it report
33410 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65  s a leak because
33420 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61   of this.** arra
33430 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b  y, then invoke [
33440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
33450 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
33460 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74  prior.** to shut
33470 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
33480 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
33490 46 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69  F12644} Automati
334a0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70  c extensions app
334b0 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68  ly across all th
334c0 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  reads. {END}.**.
334d0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
334e0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
334f0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
33500 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
33510 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
33520 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
33530 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
33540 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
33550 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72  sion(void *xEntr
33560 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  yPoint);.../*.**
33570 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
33580 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
33590 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31  sion Loading {F1
335a0 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2660}.**.** {F12
335b0 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  661} This functi
335c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20  on disables all 
335d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
335e0 74 65 72 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  tered.** automat
335f0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b  ic extensions. {
33600 45 4e 44 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f  END}  This.** ro
33610 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
33620 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
33630 72 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75  rior [sqlite3_au
33640 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  to_extension()].
33650 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  ** calls..**.** 
33660 7b 46 31 32 36 36 32 7d 20 54 68 69 73 20 63 61  {F12662} This ca
33670 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f  ll disabled auto
33680 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
33690 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
336a0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
336b0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
336c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
336d0 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
336e0 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
336f0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
33700 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
33710 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
33720 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
33730 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f  nsion(void);.../
33740 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
33750 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
33760 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
33770 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
33780 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
33790 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
337a0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
337b0 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
337c0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
337d0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
337e0 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
337f0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
33800 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
33810 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
33820 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
33830 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
33840 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
33850 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
33860 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
33870 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
33880 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c   mechanism stabl
33890 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
338a0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
338b0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
338c0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
338d0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
338e0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
338f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
33900 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
33910 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
33920 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
33930 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
33940 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
33950 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
33960 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
33970 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
33980 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
33990 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
339a0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
339b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
339c0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
339d0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
339e0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
339f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33a00 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
33a10 20 4f 62 6a 65 63 74 20 7b 46 31 38 30 30 30 7d   Object {F18000}
33a20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
33a30 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a  lite3_module.**.
33a40 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61  ** A module is a
33a50 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61   class of virtua
33a60 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20  l tables.  Each 
33a70 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65  module is define
33a80 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61  d.** by an insta
33a90 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  nce of the follo
33aa0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20  wing structure. 
33ab0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
33ac0 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74  consists.** most
33ad0 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
33ae0 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  r the module..*/
33af0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
33b00 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
33b10 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
33b20 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
33b30 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
33b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
33b50 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
33b60 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
33b70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33b80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
33b90 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
33ba0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
33bb0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
33bc0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
33bd0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
33be0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
33bf0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
33c00 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
33c10 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
33c20 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
33c30 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
33c40 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
33c50 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
33c60 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
33c70 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
33c80 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
33c90 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
33ca0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
33cb0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
33cc0 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
33cd0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
33ce0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
33cf0 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
33d00 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
33d10 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
33d20 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
33d30 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
33d40 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
33d50 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
33d60 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
33d70 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
33d80 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
33d90 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
33da0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
33db0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
33dc0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
33dd0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
33de0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
33df0 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
33e00 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
33e10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33e20 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
33e30 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
33e40 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
33e50 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
33e60 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
33e70 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
33e80 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
33e90 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
33ea0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
33eb0 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
33ec0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
33ed0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
33ee0 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
33ef0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
33f00 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
33f10 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
33f20 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
33f30 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
33f40 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
33f50 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
33f60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
33f70 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
33f80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33f90 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
33fa0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
33fb0 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
33fc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33fe0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
33ff0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
34000 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28  ppArg);..  int (
34010 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
34020 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
34030 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
34040 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
34050 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
34060 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
34070 6f 72 6d 61 74 69 6f 6e 20 7b 46 31 38 31 30 30  ormation {F18100
34080 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  }.** KEYWORDS: s
34090 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
340a0 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
340b0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
340c0 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
340d0 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
340e0 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73  s used to.** pas
340f0 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
34100 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
34110 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
34120 65 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20  e xBestIndex.** 
34130 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c  method of an sql
34140 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68  ite3_module.  Th
34150 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a  e fields under *
34160 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68  *Inputs** are th
34170 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78  e.** inputs to x
34180 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72  BestIndex and ar
34190 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42  e read-only.  xB
341a0 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73  estIndex inserts
341b0 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20   its.** results 
341c0 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75  into the **Outpu
341d0 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a  ts** fields..**.
341e0 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
341f0 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72  nt[] array recor
34200 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ds WHERE clause 
34210 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74  constraints of t
34220 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  he.** form:.**.*
34230 2a 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e  *         column
34240 20 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57   OP expr.**.** W
34250 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c  here OP is =, &l
34260 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c  t;, &lt;=, &gt;,
34270 20 6f 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20   or &gt;=.  .** 
34280 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f  The particular o
34290 70 65 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65  perator is store
342a0 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61  d.** in aConstra
342b0 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69  int[].op.  The i
342c0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
342d0 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  mn is stored in 
342e0 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
342f0 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e  ].iColumn.  aCon
34300 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
34310 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
34320 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
34330 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
34340 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
34350 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
34360 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
34370 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
34380 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a   if it cannot..*
34390 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a  *.** The optimiz
343a0 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
343b0 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
343c0 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
343d0 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
343e0 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
343f0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
34400 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
34410 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
34420 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
34430 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
34440 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
34450 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
34460 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
34470 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
34480 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
34490 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
344a0 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63  e terms in the c
344b0 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74  orrect.** form t
344c0 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65  hat refer to the
344d0 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
344e0 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20  ual table being 
344f0 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  queried..**.** I
34500 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
34510 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
34520 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
34530 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
34540 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f   Each term of aO
34550 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61  rderBy records a
34560 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f   column of the O
34570 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a  RDER BY clause..
34580 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49  **.** The xBestI
34590 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74  ndex method must
345a0 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
345b0 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
345c0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
345d0 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
345e0 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
345f0 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49  ilter.  If argvI
34600 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
34610 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
34620 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
34630 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
34640 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
34650 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
34660 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
34670 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
34680 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e  .  If aConstrain
34690 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
346a0 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
346b0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
346c0 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
346d0 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
346e0 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
346f0 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
34700 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
34710 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
34720 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
34730 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
34740 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
34750 73 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72  sed into xFilter
34760 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  ..** sqlite3_fre
34770 65 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66  e() is used to f
34780 72 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65  ree idxPtr if ne
34790 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
347a0 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s true..**.** Th
347b0 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
347c0 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
347d0 70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72  put from xFilter
347e0 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
347f0 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
34800 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
34810 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
34820 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
34830 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
34840 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
34850 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73  ed..**.** The es
34860 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
34870 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
34880 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
34890 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
348a0 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
348b0 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
348c0 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
348d0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
348e0 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
348f0 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
34900 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
34910 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
34920 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
34930 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
34940 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
34950 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
34960 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
34970 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
34980 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
34990 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
349a0 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
349b0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
349c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
349d0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
349e0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
349f0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
34a00 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
34a10 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
34a20 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
34a30 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
34a40 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
34a50 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
34a60 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
34a70 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
34a80 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
34a90 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
34aa0 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
34ab0 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
34ac0 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
34ad0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
34ae0 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
34af0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
34b00 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
34b10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
34b20 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
34b30 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
34b40 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
34b50 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
34b60 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
34b70 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
34b80 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
34b90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
34ba0 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
34bb0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
34bc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
34bd0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
34be0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
34bf0 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
34c00 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
34c10 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
34c20 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
34c30 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
34c40 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
34c50 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a   clause */..  /*
34c60 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
34c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
34c80 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
34c90 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
34ca0 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
34cb0 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
34cc0 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
34cd0 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
34ce0 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
34cf0 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
34d00 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
34d10 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
34d20 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
34d30 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
34d40 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
34d50 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
34d60 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
34d70 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
34d80 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
34d90 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
34da0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
34db0 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
34dc0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
34dd0 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
34de0 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
34df0 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
34e00 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
34e10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
34e20 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
34e30 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
34e40 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
34e50 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
34e60 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
34e70 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
34e80 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
34e90 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
34ea0 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
34eb0 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
34ec0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34ed0 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
34ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
34ef0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
34f00 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
34f10 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34f20 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
34f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
34f40 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
34f50 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
34f60 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
34f70 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
34f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34f90 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
34fa0 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
34fb0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
34fc0 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
34fd0 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
34fe0 6f 6e 20 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a  on {F18200}.**.*
34ff0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
35000 73 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  s used to regist
35010 65 72 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20  er a new module 
35020 6e 61 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c  name with an SQL
35030 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ite.** connectio
35040 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  n.  Module names
35050 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
35060 72 65 64 20 62 65 66 6f 72 65 20 63 72 65 61 74  red before creat
35070 69 6e 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75  ing new.** virtu
35080 61 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65  al tables on the
35090 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f   module, or befo
350a0 72 65 20 75 73 69 6e 67 20 70 72 65 65 78 69 73  re using preexis
350b0 74 69 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20  ting virtual.** 
350c0 74 61 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f  tables of the mo
350d0 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dule..*/.int sql
350e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
350f0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
35100 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
35110 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
35120 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
35130 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
35140 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35150 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
35160 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
35170 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
35180 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
35190 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
351a0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
351b0 0a 20 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20  .  void *       
351c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
351d0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
351e0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
351f0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
35200 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
35210 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
35220 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
35230 20 7b 46 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F18210}.**.** 
35240 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
35250 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65  identical to the
35260 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35270 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68 6f 64 20  module() method 
35280 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74  above,.** except
35290 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20   that it allows 
352a0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
352b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63  ction to be spec
352c0 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20  ified. It is.** 
352d0 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69  even more experi
352e0 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20  mental than the 
352f0 72 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74  rest of the virt
35300 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a  ual tables API..
35310 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
35320 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
35330 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
35340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35350 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
35360 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
35370 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
35380 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35390 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
353a0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
353b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
353c0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
353d0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
353e0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
353f0 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
35400 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
35410 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
35420 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
35430 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
35440 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
35450 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
35460 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
35470 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35480 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
35490 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
354a0 74 20 7b 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45  t {F18010}.** KE
354b0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
354c0 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  vtab.**.** Every
354d0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
354e0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
354f0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
35500 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
35510 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
35520 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e   a particular in
35530 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f  stance of the mo
35540 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63  dule.  Each subc
35550 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
35560 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
35570 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
35580 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
35590 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54  lementation.   T
355a0 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66  he.** purpose of
355b0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
355c0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
355d0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
355e0 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20  t are common.** 
355f0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
35600 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
35610 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
35620 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20  les methods can 
35630 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  set an error mes
35640 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e  sage by assignin
35650 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62  g a.** string ob
35660 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
35670 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f  te3_mprintf() to
35680 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
35690 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
356a0 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
356b0 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
356c0 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
356d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ll to sqlite3_fr
356e0 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ee().** prior to
356f0 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77   assigning a new
35700 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d   string to zErrM
35710 73 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65  sg.  After the e
35720 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
35730 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20  is delivered up 
35740 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70  to the client ap
35750 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73  plication, the s
35760 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75  tring will be au
35770 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66  tomatically.** f
35780 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  reed by sqlite3_
35790 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a  free() and the z
357a0 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c  ErrMsg field wil
357b0 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f  l be zeroed.  No
357c0 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74  te.** that sqlit
357d0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
357e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
357f0 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20  are used on the 
35800 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a  zErrMsg field.**
35810 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74   since virtual t
35820 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e  ables are common
35830 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  ly implemented i
35840 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e  n loadable exten
35850 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64  sions which.** d
35860 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  o not have acces
35870 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69  s to sqlite3MPri
35880 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ntf() or sqlite3
35890 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63  Free()..*/.struc
358a0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b  t sqlite3_vtab {
358b0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
358c0 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65  _module *pModule
358d0 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65  ;  /* The module
358e0 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61   for this virtua
358f0 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74  l table */.  int
35900 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20   nRef;          
35910 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35920 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
35930 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
35940 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
35950 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
35960 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
35970 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
35980 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
35990 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
359a0 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
359b0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
359c0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
359d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
359e0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
359f0 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 46 31 38  sor Object  {F18
35a00 30 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  020}.** KEYWORDS
35a10 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
35a20 75 72 73 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72  ursor.**.** Ever
35a30 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  y module impleme
35a40 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
35a50 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66  ubclass of the f
35a60 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
35a70 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62  re.** to describ
35a80 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
35a90 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69  oint into the vi
35aa0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
35ab0 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
35ac0 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
35ad0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
35ae0 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
35af0 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
35b00 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
35b10 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
35b20 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
35b30 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
35b40 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
35b50 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
35b60 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
35b70 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
35b80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
35b90 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
35ba0 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
35bb0 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
35bc0 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
35bd0 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
35be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
35bf0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
35c00 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
35c10 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
35c20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
35c30 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
35c40 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
35c50 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
35c60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35c70 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
35c80 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
35c90 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
35ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35cb0 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
35cc0 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
35cd0 61 62 6c 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a  able {F18280}.**
35ce0 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20  .** The xCreate 
35cf0 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
35d00 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65  hods of a module
35d10 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
35d20 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63  ng API.** to dec
35d30 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
35d40 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
35d50 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
35d60 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
35d70 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
35d80 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
35d90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35da0 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
35db0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
35dc0 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65  ar *zCreateTable
35dd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35de0 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
35df0 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
35e00 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38  rtual Table {F18
35e10 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  300}.**.** Virtu
35e20 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72  al tables can pr
35e30 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76  ovide alternativ
35e40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35e50 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  s of functions.*
35e60 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e  * using the xFin
35e70 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64  dFunction method
35e80 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  .  But global ve
35e90 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
35ea0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
35eb0 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
35ec0 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
35ed0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  d..**.** This AP
35ee0 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67  I makes sure a g
35ef0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66  lobal version of
35f00 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
35f10 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
35f20 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72   name and number
35f30 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65   of parameters e
35f40 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75  xists.  If no su
35f50 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73  ch function exis
35f60 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  ts.** before thi
35f70 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c  s API is called,
35f80 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20   a new function 
35f90 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
35fa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
35fb0 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75  ** of the new fu
35fc0 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61  nction always ca
35fd0 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f  uses an exceptio
35fe0 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20  n to be thrown. 
35ff0 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66   So.** the new f
36000 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
36010 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67  ood for anything
36020 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73   by itself.  Its
36030 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65   only.** purpose
36040 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63   is to be a plac
36050 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  e-holder functio
36060 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
36070 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76  erloaded.** by v
36080 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a  irtual tables..*
36090 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68  *.** This API sh
360a0 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72  ould be consider
360b0 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76  ed part of the v
360c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
360d0 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68  erface,.** which
360e0 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
360f0 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20   and subject to 
36100 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
36110 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
36120 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
36130 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
36140 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
36150 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
36160 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
36170 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
36180 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
36190 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
361a0 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
361b0 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
361c0 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
361d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
361e0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
361f0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
36200 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
36210 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
36220 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
36230 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
36240 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
36250 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
36260 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
36270 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
36280 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
36290 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
362a0 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
362b0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
362c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
362d0 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
362e0 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
362f0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
36300 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
36310 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
36320 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
36330 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
36340 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
36350 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
36360 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
36370 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37  n Open BLOB {F17
36380 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  800}.**.** An in
36390 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
363a0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
363b0 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
363c0 20 77 68 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d   which.** increm
363d0 65 6e 74 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65  ental I/O can be
363e0 20 70 72 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f   preformed..** O
363f0 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74  bjects of this t
36400 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20  ype are created 
36410 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  by.** [sqlite3_b
36420 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
36430 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
36440 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
36450 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
36460 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
36470 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
36480 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74  lob_write()] int
36490 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62  erfaces.** can b
364a0 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  e used to read o
364b0 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75  r write small su
364c0 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  bsections of the
364d0 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73   blob..** The [s
364e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
364f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
36500 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
36510 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69  of the.** blob i
36520 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
36530 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
36540 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
36550 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
36560 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
36570 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
36580 61 6c 20 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a  al I/O {F17810}.
36590 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
365a0 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61  faces opens a ha
365b0 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62  ndle to the blob
365c0 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
365d0 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
365e0 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
365f0 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
36600 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
36610 68 65 72 20 77 6f 72 64 73 2c 20 20 74 68 65 20  her words,  the 
36620 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77  same blob that w
36630 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
36640 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
36650 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
36660 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
36670 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77  zTable WHERE row
36680 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  id = iRow;.** </
36690 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
366a0 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
366b0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
366c0 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73  ero, the blob is
366d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20   opened for .** 
366e0 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
366f0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
36700 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69  zero, the blob i
36710 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
36720 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a  d .** access..**
36730 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
36740 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
36750 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
36760 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  new .** [sqlite3
36770 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e  _blob | blob han
36780 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20  dle] is written 
36790 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20  to *ppBlob. .** 
367a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  Otherwise an err
367b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
367c0 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20  ned and .** any 
367d0 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f  value written to
367e0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20   *ppBlob should 
367f0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74  not be used by t
36800 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68  he caller..** Th
36810 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
36820 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61   the database-ha
36830 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20  ndle error code 
36840 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
36850 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
36860 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
36870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
36880 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a  rrmsg()]..** .**
36890 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
368a0 2a 2a 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75  ** {F17813} A su
368b0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
368c0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
368d0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c  te3_blob_open(D,
368e0 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a  B,T,C,R,F,P)].**
368f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
36900 61 63 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71  ace opens an [sq
36910 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65  lite3_blob] obje
36920 63 74 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62  ct P on the blob
36930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
36940 63 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c  column C of tabl
36950 65 20 54 20 69 6e 20 64 61 74 61 62 61 73 65 20  e T in database 
36960 42 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  B on [database c
36970 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
36980 0a 2a 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73  .** {F17814} A s
36990 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
369a0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
369b0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e  _blob_open(D,...
369c0 29 5d 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20  )] starts.**    
369d0 20 20 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e        a new tran
369e0 73 61 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61  saction on [data
369f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36a00 20 44 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65   D if that conne
36a10 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
36a20 20 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79    is not already
36a30 20 69 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f   in a transactio
36a40 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36  n..**.** {F17816
36a50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
36a60 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43  lob_open(D,B,T,C
36a70 2c 52 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  ,R,F,P)] interfa
36a80 63 65 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f  ce opens the blo
36a90 62 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  b.**          fo
36aa0 72 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  r read and write
36ab0 20 61 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f   access if and o
36ac0 6e 6c 79 20 69 66 20 74 68 65 20 46 20 70 61 72  nly if the F par
36ad0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
36ae0 20 20 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a     is non-zero..
36af0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54  **.** {F17819} T
36b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
36b10 5f 6f 70 65 6e 28 29 5d 20 69 6e 74 65 72 66 61  _open()] interfa
36b20 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ce returns [SQLI
36b30 54 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20  TE_OK] on .**   
36b40 20 20 20 20 20 20 20 73 75 63 63 65 73 73 20 61         success a
36b50 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
36b60 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
36b70 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
36b80 20 7b 46 31 37 38 32 31 7d 20 49 66 20 61 6e 20   {F17821} If an 
36b90 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
36ba0 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ing evaluation o
36bb0 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  f [sqlite3_blob_
36bc0 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20  open(D,...)].** 
36bd0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 75           then su
36be0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
36bf0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
36c00 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  de(D)],.**      
36c10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
36c20 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71  msg(D)], and [sq
36c30 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44  lite3_errmsg16(D
36c40 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
36c50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72  *          infor
36c60 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74  mation approprat
36c70 65 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72  e for that error
36c80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36c90 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
36ca0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
36cb0 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
36cc0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
36cd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36ce0 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
36cf0 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
36d00 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
36d10 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
36d20 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
36d30 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20  I3REF:  Close A 
36d40 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37  BLOB Handle {F17
36d50 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  830}.**.** Close
36d60 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
36d70 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
36d80 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  ndle]..**.** Clo
36d90 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
36da0 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
36db0 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
36dc0 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
36dd0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
36de0 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
36df0 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
36e00 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
36e10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
36e20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61  nnection is in a
36e30 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a  utocommit mode..
36e40 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73  ** If any writes
36e50 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68   were made to th
36e60 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67  e BLOB, they mig
36e70 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61  ht be held in ca
36e80 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65  che.** until the
36e90 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e   close operation
36ea0 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69   if they will fi
36eb0 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73  t. {END}.** Clos
36ec0 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74  ing the BLOB oft
36ed0 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68  en forces the ch
36ee0 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20  anges.** out to 
36ef0 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61  disk and so if a
36f00 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63  ny I/O errors oc
36f10 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c  cur, they will l
36f20 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61  ikely occur.** a
36f30 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
36f40 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  the BLOB is clos
36f50 65 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e  ed.  {F17833} An
36f60 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  y errors that oc
36f70 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c  cur during.** cl
36f80 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74  osing are report
36f90 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  ed as a non-zero
36fa0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a   return value..*
36fb0 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73  *.** The BLOB is
36fc0 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
36fd0 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
36fe0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
36ff0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
37000 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
37010 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
37020 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
37030 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  NTS:.**.** {F178
37040 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
37050 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20  _blob_close(P)] 
37060 69 6e 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73  interface closes
37070 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
37080 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
37090 62 6a 65 63 74 20 50 20 70 72 65 76 69 6f 75 73  bject P previous
370a0 6c 79 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a  ly opened using.
370b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
370c0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
370d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 36  ]..**.** {F17836
370e0 7d 20 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 73 71  } Closing an [sq
370f0 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65  lite3_blob] obje
37100 63 74 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ct using.**     
37110 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c       [sqlite3_bl
37120 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 73 68 61 6c  ob_close()] shal
37130 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
37140 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
37150 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  to.**          c
37160 6f 6d 6d 69 74 20 69 66 20 74 68 65 72 65 20 61  ommit if there a
37170 72 65 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e  re no other open
37180 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
37190 6f 62 6a 65 63 74 73 0a 2a 2a 20 20 20 20 20 20  objects.**      
371a0 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64      or [prepared
371b0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 6e 20   statements] on 
371c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
371d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
371e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  nd.**          t
371f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37200 6e 65 63 74 69 6f 6e 5d 20 69 73 20 69 6e 0a 2a  nection] is in.*
37210 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37220 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
37230 69 74 20 7c 20 61 75 74 6f 63 6f 6d 6d 69 74 20  it | autocommit 
37240 6d 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mode]..**.** {F1
37250 37 38 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  7839} The [sqlit
37260 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29  e3_blob_close(P)
37270 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 6c 6f  ] interfaces clo
37280 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ses the .**     
37290 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c       [sqlite3_bl
372a0 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e 63  ob] object P unc
372b0 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76  onditionally, ev
372c0 65 6e 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  en if.**        
372d0 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f    [sqlite3_blob_
372e0 63 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e  close(P)] return
372f0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
37300 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
37310 4b 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  K]..**          
37320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37330 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74  blob_close(sqlit
37340 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
37350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52 65  ** CAPI3REF:  Re
37360 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
37370 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46   An Open BLOB {F
37380 31 37 38 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  17840}.**.** Ret
37390 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69 6e 20  urn the size in 
373a0 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f  bytes of the blo
373b0 62 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  b accessible via
373c0 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73   the open .** [s
373d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a  qlite3_blob] obj
373e0 65 63 74 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  ect in its only 
373f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37400 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37410 2a 20 7b 46 31 37 38 34 33 7d 20 54 68 65 20 5b  * {F17843} The [
37420 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
37430 65 73 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  es(P)] interface
37440 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
37450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
37460 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
37470 4f 42 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  OB that the [sql
37480 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63  ite3_blob] objec
37490 74 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t P.**          
374a0 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2f 0a 69 6e  refers to..*/.in
374b0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
374c0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
374d0 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
374e0 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 74  I3REF:  Read Dat
374f0 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
37500 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37  crementally {F17
37510 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  850}.**.** This 
37520 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
37530 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
37540 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b  om an open .** [
37550 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
37560 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  lob-handle] into
37570 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69   a caller suppli
37580 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 4e 20  ed buffer..** N 
37590 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
375a0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
375b0 66 66 65 72 0a 2a 2a 20 5a 20 66 72 6f 6d 20 74  ffer.** Z from t
375c0 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74  he open blob, st
375d0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
375e0 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
375f0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
37600 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
37610 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
37620 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c  end of the blob,
37630 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
37640 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
37650 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
37660 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f  ead.  If N or iO
37670 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
37680 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49   than zero [SQLI
37690 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
376a0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
376b0 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  a is read..**.**
376c0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
376d0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
376e0 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
376f0 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  n .** [error cod
37700 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
37710 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
37720 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
37730 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37740 0a 2a 2a 20 7b 46 31 37 38 35 33 7d 20 54 68 65  .** {F17853} The
37750 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
37760 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e  ead(P,Z,N,X)] in
37770 74 65 72 66 61 63 65 20 72 65 61 64 73 20 4e 20  terface reads N 
37780 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
37790 20 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f    beginning at o
377a0 66 66 73 65 74 20 58 20 66 72 6f 6d 0a 2a 2a 20  ffset X from.** 
377b0 20 20 20 20 20 20 20 20 20 74 68 65 20 62 6c 6f           the blo
377c0 62 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  b that [sqlite3_
377d0 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 72  blob] object P r
377e0 65 66 65 72 73 20 74 6f 0a 2a 2a 20 20 20 20 20  efers to.**     
377f0 20 20 20 20 20 61 6e 64 20 77 72 69 74 65 73 20       and writes 
37800 74 68 6f 73 65 20 4e 20 62 79 74 65 73 20 69 6e  those N bytes in
37810 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a  to buffer Z..**.
37820 2a 2a 20 7b 46 31 37 38 35 36 7d 20 49 6e 20 5b  ** {F17856} In [
37830 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
37840 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74  d(P,Z,N,X)] if t
37850 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
37860 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lob.**          
37870 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58  is less than N+X
37880 20 62 79 74 65 73 2c 20 74 68 65 6e 20 74 68 65   bytes, then the
37890 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
378a0 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  s [SQLITE_ERROR]
378b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
378c0 20 6e 6f 74 68 69 6e 67 20 69 73 20 72 65 61 64   nothing is read
378d0 20 66 72 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a   from the blob..
378e0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 39 7d 20 49  **.** {F17859} I
378f0 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  n [sqlite3_blob_
37900 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69  read(P,Z,N,X)] i
37910 66 20 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 73  f X or N is less
37920 20 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 20   than zero.**   
37930 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
37940 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
37950 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a   [SQLITE_ERROR].
37960 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
37970 6e 6f 74 68 69 6e 67 20 69 73 20 72 65 61 64 20  nothing is read 
37980 66 72 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a 2a  from the blob..*
37990 2a 0a 2a 2a 20 7b 46 31 37 38 36 32 7d 20 54 68  *.** {F17862} Th
379a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
379b0 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69  read(P,Z,N,X)] i
379c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
379d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20   [SQLITE_OK].** 
379e0 20 20 20 20 20 20 20 20 20 69 66 20 4e 20 62 79           if N by
379f0 74 65 73 20 77 68 65 72 65 20 73 75 63 63 65 73  tes where succes
37a00 73 66 75 6c 6c 79 20 72 65 61 64 20 69 6e 74 6f  sfully read into
37a10 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a   buffer Z..**.**
37a20 20 7b 46 31 37 38 36 35 7d 20 49 66 20 74 68 65   {F17865} If the
37a30 20 72 65 71 75 65 73 74 65 64 20 72 65 61 64 20   requested read 
37a40 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d  could not be com
37a50 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  pleted,.**      
37a60 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
37a70 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e  _blob_read(P,Z,N
37a80 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,X)] interface r
37a90 65 74 75 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20  eturns an.**    
37aa0 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74        appropriat
37ab0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
37ac0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
37ad0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  r code]..**.** {
37ae0 46 31 37 38 36 38 7d 20 49 66 20 61 6e 20 65 72  F17868} If an er
37af0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
37b00 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  g evaluation of 
37b10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
37b20 61 64 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ad(D,...)].**   
37b30 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73         then subs
37b40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
37b50 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
37b60 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (D)],.**        
37b70 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
37b80 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  g(D)], and [sqli
37b90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
37ba0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
37bb0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
37bc0 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20  tion approprate 
37bd0 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a  for that error..
37be0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
37bf0 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
37c00 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
37c10 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
37c20 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
37c30 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44  PI3REF:  Write D
37c40 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20  ata Into A BLOB 
37c50 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46  Incrementally {F
37c60 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  17870}.**.** Thi
37c70 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
37c80 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
37c90 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a   into an open .*
37ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
37cb0 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66  | blob-handle] f
37cc0 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c  rom a user suppl
37cd0 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e  ied buffer..** n
37ce0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
37cf0 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
37d00 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69  he buffer.** poi
37d10 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74  nted to by z int
37d20 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  o the open blob,
37d30 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
37d40 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
37d50 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
37d60 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
37d70 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
37d80 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37d90 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  ent.** was not o
37da0 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e  pened for writin
37db0 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
37dc0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
37dd0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
37de0 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74  *** was zero), t
37df0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
37e00 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
37e10 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  DONLY]..**.** Th
37e20 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
37e30 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
37e40 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
37e50 62 6c 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20 6e  blob; it is.** n
37e60 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
37e70 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
37e80 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67   of a blob using
37e90 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66   this API..** If
37ea0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
37eb0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62  is less than n b
37ec0 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
37ed0 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a  d of the blob, .
37ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
37ef0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
37f00 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
37f10 74 74 65 6e 2e 20 20 49 66 20 6e 20 69 73 0a 2a  tten.  If n is.*
37f20 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
37f30 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
37f40 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
37f50 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
37f60 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  en..**.** On suc
37f70 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
37f80 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68  is returned. Oth
37f90 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b  erwise, an .** [
37fa0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
37fb0 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
37fc0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
37fd0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
37fe0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
37ff0 37 38 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  7873} The [sqlit
38000 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c  e3_blob_write(P,
38010 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63  Z,N,X)] interfac
38020 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73  e writes N bytes
38030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
38040 6d 20 62 75 66 66 65 72 20 5a 20 69 6e 74 6f 0a  m buffer Z into.
38050 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
38060 62 6c 6f 62 20 74 68 61 74 20 5b 73 71 6c 69 74  blob that [sqlit
38070 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20  e3_blob] object 
38080 50 20 72 65 66 65 72 73 20 74 6f 0a 2a 2a 20 20  P refers to.**  
38090 20 20 20 20 20 20 20 20 62 65 67 69 6e 6e 69 6e          beginnin
380a0 67 20 61 74 20 61 6e 20 6f 66 66 73 65 74 20 6f  g at an offset o
380b0 66 20 58 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f  f X into the blo
380c0 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 35  b..**.** {F17875
380d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
380e0 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c  lob_write(P,Z,N,
380f0 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  X)] interface re
38100 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
38110 20 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    [SQLITE_READON
38120 4c 59 5d 20 69 66 20 74 68 65 20 5b 73 71 6c 69  LY] if the [sqli
38130 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
38140 20 50 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20   P was.**       
38150 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62     [sqlite3_blob
38160 5f 6f 70 65 6e 20 7c 20 6f 70 65 6e 65 64 5d 20  _open | opened] 
38170 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79  for reading only
38180 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d  ..**.** {F17876}
38190 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   In [sqlite3_blo
381a0 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29  b_write(P,Z,N,X)
381b0 5d 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  ] if the size of
381c0 20 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20   the blob.**    
381d0 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68        is less th
381e0 61 6e 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68  an N+X bytes, th
381f0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
38200 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
38210 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20  ERROR].**       
38220 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69     and nothing i
38230 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
38240 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b  he blob..**.** {
38250 46 31 37 38 37 39 7d 20 49 6e 20 5b 73 71 6c 69  F17879} In [sqli
38260 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50  te3_blob_write(P
38270 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72  ,Z,N,X)] if X or
38280 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
38290 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  zero.**         
382a0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
382b0 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
382c0 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20  TE_ERROR].**    
382d0 20 20 20 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e        and nothin
382e0 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  g is written int
382f0 6f 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a  o the blob..**.*
38300 2a 20 7b 46 31 37 38 38 32 7d 20 54 68 65 20 5b  * {F17882} The [
38310 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
38320 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74  te(P,Z,N,X)] int
38330 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b  erface returns [
38340 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20  SQLITE_OK].**   
38350 20 20 20 20 20 20 20 69 66 20 4e 20 62 79 74 65         if N byte
38360 73 20 77 68 65 72 65 20 73 75 63 63 65 73 73 66  s where successf
38370 75 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ully written int
38380 6f 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o blob..**.** {F
38390 31 37 38 38 35 7d 20 49 66 20 74 68 65 20 72 65  17885} If the re
383a0 71 75 65 73 74 65 64 20 77 72 69 74 65 20 63 6f  quested write co
383b0 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c  uld not be compl
383c0 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  eted,.**        
383d0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62    the [sqlite3_b
383e0 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c  lob_write(P,Z,N,
383f0 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  X)] interface re
38400 74 75 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20 20  turns an.**     
38410 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65       appropriate
38420 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
38430 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
38440 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46   code]..**.** {F
38450 31 37 38 38 38 7d 20 49 66 20 61 6e 20 65 72 72  17888} If an err
38460 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
38470 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
38480 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
38490 74 65 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  te(D,...)].**   
384a0 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73         then subs
384b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
384c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
384d0 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (D)],.**        
384e0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
384f0 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  g(D)], and [sqli
38500 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
38510 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
38520 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
38530 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20  tion approprate 
38540 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a  for that error..
38550 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
38560 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65  lob_write(sqlite
38570 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20  3_blob *, const 
38580 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20  void *z, int n, 
38590 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
385a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
385b0 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73  Virtual File Sys
385c0 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 46 31 31  tem Objects {F11
385d0 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  200}.**.** A vir
385e0 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
385f0 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
38600 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
38610 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
38620 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
38630 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
38640 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
38650 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
38660 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
38670 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
38680 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
38690 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
386a0 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
386b0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
386c0 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
386d0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
386e0 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
386f0 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
38700 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
38710 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
38720 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
38730 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66  * The sqlite3_vf
38740 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61  s_find() interfa
38750 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
38760 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46  nter to .** a VF
38770 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
38780 2e 20 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73  .  Names are cas
38790 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20  e sensitive..** 
387a0 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74  Names are zero-t
387b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
387c0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74  strings..** If t
387d0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
387e0 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  , a NULL.** poin
387f0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
38800 20 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73    If zVfsName is
38810 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
38820 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69  efault .** VFS i
38830 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a  s returned. .**.
38840 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65  ** New VFSes are
38850 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
38860 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
38870 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68  ister()..** Each
38880 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73   new VFS becomes
38890 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
388a0 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74   if the makeDflt
388b0 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a   flag is set..**
388c0 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61   The same VFS ca
388d0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
388e0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
388f0 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a  ithout injury..*
38900 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69  * To make an exi
38910 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74  sting VFS into t
38920 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20  he default VFS, 
38930 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69  register it agai
38940 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61  n.** with the ma
38950 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e  keDflt flag set.
38960 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65    If two differe
38970 6e 74 20 56 46 53 65 73 20 77 69 74 6