/ Hex Artifact Content
Login

Artifact a65fd6667df5b8a8abc287edebe6b4b82c10cce1:


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 38 30 20 32 30 30 38 2f  in,v 1.280 2008/
05f0: 30 31 2f 33 31 20 31 32 3a 32 36 3a 35 30 20 64  01/31 12:26:50 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 6f  SQLite is a stro
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 2d  VERSION_NUMBER -
0d80: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
0d90: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
0da0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
0db0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
0dc0: 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 20  ers {F10020}.** 
0dd0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
0de0: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  3_version.**.** 
0df0: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70  These features p
0e00: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
0e10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
0e20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0e30: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49  ON].** and [SQLI
0e40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0e50: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74  R] #defines in t
0e60: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61  he header, but a
0e70: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  re associated.**
0e80: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
0e90: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
0ea0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43   header file.  C
0eb0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d  autious programm
0ec0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63  ers might.** inc
0ed0: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20  lude a check in 
0ee0: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
0ef0: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  n to verify that
0f00: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62   .** sqlite3_lib
0f10: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
0f20: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
0f30: 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b 53  the value .** [S
0f40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f50: 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MBER]..**.** The
0f60: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
0f70: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
0f80: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20  eturns the same 
0f90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
0fa0: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69  s.** in the sqli
0fb0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
0fc0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
0fd0: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  The function is 
0fe0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
0ff0: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
1000: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
1010: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  lly do not have 
1020: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1030: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74   string.** const
1040: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
1050: 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  DLL..**.** INVAR
1060: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1070: 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0021} The [sqlit
1080: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1090: 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  mber()] interfac
10a0: 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  e returns an int
10b0: 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
10c0: 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54   equal to [SQLIT
10d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
10e0: 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32  ]. .**.** {F1002
10f0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1100: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
1110: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1120: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68  s the text of th
1130: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
1140: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1150: 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  tring. .**.** {F
1160: 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  10023} The [sqli
1170: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1180: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1190: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
11a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
11b0: 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e  [sqlite3_version
11c0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
11d0: 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  t..*/.SQLITE_EXT
11e0: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1200: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1210: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1220: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
1230: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1240: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
1260: 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65  st To See If The
1270: 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65   Library Is Thre
1280: 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d 0a  adsafe {F10100}.
1290: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
12a0: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
12b0: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
12c0: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
12d0: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
12e0: 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65 73  SAFE C preproces
12f0: 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75  sor macro is tru
1300: 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  e, mutexes.** ar
1310: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1320: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1330: 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d  fe.  When that m
1340: 61 63 72 6f 20 6f 73 20 66 61 6c 73 65 2c 0a 2a  acro os false,.*
1350: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1360: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1370: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1380: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1390: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
13a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
13b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
13c0: 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65 61  * There is a mea
13d0: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
13e0: 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72 20  nce penalty for 
13f0: 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  enabling mutexes
1400: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1410: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1420: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1430: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1440: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1450: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1460: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1470: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1480: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
1490: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
14b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
14c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
14d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
14e0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
14f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1500: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1510: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1520: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1530: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1540: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1550: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1560: 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  e SQLITE_THREADS
1570: 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  AFE macro..**.**
1580: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1590: 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65 20  ** {F10101} The 
15a0: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
15b0: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  afe()] function 
15c0: 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f 20  returns nonzero 
15d0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
15e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
15f0: 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74 65  ed with its mute
1600: 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 7a  xes enabled or z
1610: 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ero.**          
1620: 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  if SQLite was co
1630: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1640: 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f  xes disabled..*/
1650: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
1660: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
1670: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1680: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1690: 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32 30  ion Handle {F120
16a0: 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
16b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
16c0: 63 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  ction}.**.** Eac
16d0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
16e0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
16f0: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72  ented by pointer
1700: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
1710: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65  of the.** opaque
1720: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
1730: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
1740: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
1750: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
1760: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
1770: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
1780: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1790: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
17a0: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
17b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
17c0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
17d0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a  ts constructors.
17e0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
17f0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20  close()] is its 
1800: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
1810: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1820: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1830: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1840: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1850: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1860: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1870: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
1880: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
1890: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
18a0: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
18b0: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  s on this.** obj
18c0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
18d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
18e0: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  qlite3;.../*.** 
18f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1900: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1910: 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F10200}.** KEYWO
1920: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
1930: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
1940: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1950: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
1960: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
1970: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
1980: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
1990: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
19a0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
19b0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
19c0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
19d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
19e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
19f0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
1a00: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
1a10: 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69 6f  ype.** definitio
1a20: 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 5f  ns.  The sqlite_
1a30: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
1a40: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
1a50: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20 66  e.** supported f
1a60: 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1a70: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
1a80: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a90: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 31  S:.**.** {F10201
1aa0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e  } The [sqlite_in
1ab0: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1ac0: 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73  3_int64] types s
1ad0: 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20 20  pecify a.**     
1ae0: 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67 6e       64-bit sign
1af0: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1b00: 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b  * {F10202} The [
1b10: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61  sqlite_uint64] a
1b20: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74  nd [sqlite3_uint
1b30: 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66  64] types specif
1b40: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1b50: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1b60: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1b70: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1b80: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1b90: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1ba0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1bb0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1bc0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
1bd0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
1be0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
1bf0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
1c00: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
1c10: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
1c20: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
1c30: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1c40: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
1c50: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c60: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
1c70: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1c80: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1c90: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
1ca0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
1cb0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
1cc0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
1cd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
1ce0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
1cf0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
1d00: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
1d10: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
1d20: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
1d30: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
1d40: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
1d50: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1d60: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1d70: 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69  ting-point.*/.#i
1d80: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
1d90: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
1da0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
1db0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
1dc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1dd0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
1de0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1df0: 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a 0a  ion {F12010}.**.
1e00: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1e10: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
1e20: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
1e30: 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a 2a  e3] object.  .**
1e40: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e50: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
1e60: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
1e70: 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70 72  lize] all.** [pr
1e80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e90: 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  s] and.** [sqlit
1ea0: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
1eb0: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c 69  close] all [sqli
1ec0: 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42 73  te3_blob | BLOBs
1ed0: 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ] .** associated
1ee0: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
1ef0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
1f00: 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  .** to attemptin
1f10: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 5b  g to close the [
1f20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
1f30: 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68 61  .**.** <todo>Wha
1f40: 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65 6e  t happens to pen
1f50: 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e  ding transaction
1f60: 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a 20  s?  Are they.** 
1f70: 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72 20  rolled back, or 
1f80: 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64 6f  abandoned?</todo
1f90: 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1fa0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  TS:.**.** {F1201
1fb0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1fc0: 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66 61  close()] interfa
1fd0: 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20 5b  ce destroys an [
1fe0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a  sqlite3] object.
1ff0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
2000: 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72  cated by a prior
2010: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2020: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20 20  3_open()],.**   
2030: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2040: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
2050: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2060: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 32  ]..**.** {F12012
2070: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2080: 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  lose()] function
2090: 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d 65   releases all me
20a0: 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68 65  mory used by the
20b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
20c0: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f 73  nection and clos
20d0: 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c 65  es all open file
20e0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 33  s..**.** {F12013
20f0: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
2100: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e  e connection con
2110: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
2120: 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2130: 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61 76  ements] that hav
2140: 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20 20  e not been.**   
2150: 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65 64         finalized
2160: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2170: 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20 5b  alize()], then [
2180: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2190: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
21a0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
21b0: 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74 68  Y] and leaves th
21c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
21d0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34  n..**.** {F12014
21e0: 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65 33  } Giving sqlite3
21f0: 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c 20  _close() a NULL 
2200: 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2210: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2220: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
2230: 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20 54  **.** {U12015} T
2240: 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
2250: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2260: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73 71  ] must be an [sq
2270: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a  lite3] object.**
2280: 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2290: 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  r previously obt
22a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
22b0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 74  te3_open()] or t
22c0: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
22d0: 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 4e  equivalent, or N
22e0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30  ULL..**.** {U120
22f0: 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74 65  16} The paramete
2300: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2310: 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74 20  ose()] must not 
2320: 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69 6f  have been previo
2330: 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
2340: 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20   closed..*/.int 
2350: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
2360: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
2370: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
2380: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2390: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
23a0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
23b0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
23c0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
23d0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
23e0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
23f0: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2400: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2410: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2420: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2430: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
2440: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
2450: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
2460: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46  ion Interface {F
2470: 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12100}.**.** The
2480: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2490: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
24a0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
24b0: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65 20   running.** one 
24c0: 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 74  or more SQL stat
24d0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 61  ements without a
24e0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
24f0: 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   The.** SQL stat
2500: 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65  ements are passe
2510: 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f  d in as the seco
2520: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
2530: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
2540: 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e  ).  The statemen
2550: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2560: 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20 75   one by one.** u
2570: 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65  ntil either an e
2580: 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
2590: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
25a0: 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c 20  red or.** until 
25b0: 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e  they are all don
25c0: 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61  e.  The 3rd para
25d0: 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74 69  meter is an opti
25e0: 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  onal.** callback
25f0: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
2600: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72   once for each r
2610: 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79 20  ow of any query 
2620: 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64 75  results.** produ
2630: 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 73  ced by the SQL s
2640: 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20  tatements.  The 
2650: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 65  5th parameter te
2660: 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20  lls where.** to 
2670: 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20  write any error 
2680: 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  messages..**.** 
2690: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
26a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
26b0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
26c0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
26d0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26e0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
26f0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2700: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
2710: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2720: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
2730: 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20 63  s nothing that c
2740: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
2750: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2760: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2770: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2780: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2790: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
27a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
27b0: 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69 65   just a convenie
27c0: 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a 2a  nt wrapper..**.*
27d0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
27e0: 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54 68   .** {F12101} Th
27f0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2800: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76 61  )] interface eva
2810: 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20 6d  luates zero or m
2820: 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ore UTF-8.**    
2830: 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20 73        encoded, s
2840: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
2850: 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ed, SQL statemen
2860: 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ts in the.**    
2870: 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
2880: 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66 20  nated string of 
2890: 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
28a0: 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a 20  r within the.** 
28b0: 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
28c0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
28d0: 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20 69  ] object given i
28e0: 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  n the 1st parame
28f0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ter..**.** {F121
2900: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
2910: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2920: 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c 49  _exec()] is SQLI
2930: 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a 20  TE_OK if all.** 
2940: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
2950: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
2960: 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  essfully..**.** 
2970: 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65 74  {F12105} The ret
2980: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  urn value of [sq
2990: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
29a0: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
29b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
29c0: 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64 65  -zero error code
29d0: 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74   if any SQL stat
29e0: 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ement fails..**.
29f0: 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20 6f  ** {F12107} If o
2a00: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2a10: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2a20: 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69   handed to [sqli
2a30: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
2a40: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72          return r
2a50: 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33  esults and the 3
2a60: 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
2a70: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a  not NULL, then.*
2a80: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2a90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2aa0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2ab0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2ac0: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  is.**          i
2ad0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2ae0: 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75  each row of resu
2af0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2b00: 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  0} If the callba
2b10: 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ck returns a non
2b20: 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e  -zero value then
2b30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2b40: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
2b50: 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 20 53  ll aborted the S
2b60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20  QL statement it 
2b70: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61  is currently eva
2b80: 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20  luating,.**     
2b90: 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75       skip all su
2ba0: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
2bb0: 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74  tements, and ret
2bc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52  urn [SQLITE_ABOR
2bd0: 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T]..**          
2be0: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
2bf0: 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 68 65  ns to *errmsg he
2c00: 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 72 65  re?  Does the re
2c10: 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  sult code for.**
2c20: 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
2c30: 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 74 20  3_errcode() get 
2c40: 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  set?</todo>.**.*
2c50: 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b  * {F12113} The [
2c60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2c70: 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 61 73  routine will pas
2c80: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
2c90: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
2ca0: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
2cb0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
2cc0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2cd0: 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65  .** {F12116} The
2ce0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2cf0: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
2d00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2d10: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
2d20: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
2d30: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
2d40: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2d50: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
2d60: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
2d70: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39  t..**.** {F12119
2d80: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2d90: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2da0: 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61  ets the 3rd para
2db0: 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a  meter of its .**
2dc0: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
2dd0: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
2de0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
2df0: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
2e00: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e10: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
2e20: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2e30: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
2e40: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
2e50: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
2e60: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2e70: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
2e80: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
2e90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2ea0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
2eb0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   4th parameter o
2ec0: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
2ed0: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
2ee0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2ef0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2f00: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
2f10: 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f           names o
2f20: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
2f30: 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
2f40: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
2f50: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
2f60: 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65   {F12125} If the
2f70: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2f80: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
2f90: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
2fa0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2fb0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76  ite3_exec()] nev
2fc0: 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c  er invokes a cal
2fd0: 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72  lback.  All quer
2fe0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
2ff0: 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74  sults are silent
3000: 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  ly discarded..**
3010: 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 66 20  .** {F12128} If 
3020: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3030: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3040: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3050: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3060: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3070: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
3080: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 68 65  ite3_exec()] the
3090: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
30a0: 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 20 20  )] will.**      
30b0: 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 5b 65      return an [e
30c0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
30d0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
30e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 31  ]..**.** {F12131
30f0: 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  } If an error oc
3100: 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 69  curs while parsi
3110: 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ng or evaluating
3120: 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a   any of the SQL.
3130: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
3140: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ed to [sqlite3_e
3150: 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 74 68  xec()] and if th
3160: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3170: 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 20 20  (errmsg).**     
3180: 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33       to [sqlite3
3190: 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f 74 20  _exec()] is not 
31a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 65 72  NULL, then an er
31b0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 0a 2a  ror message is.*
31c0: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
31d0: 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 65  ated using the e
31e0: 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b 73 71  quivalent of [sq
31f0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
3200: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
3210: 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64 65   *errmsg is made
3220: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 61   to point to tha
3230: 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  t message..**.**
3240: 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {F12134} The [s
3250: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3260: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
3270: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
3280: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3290: 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 6d 73  *errmsg if errms
32a0: 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  g is NULL or if 
32b0: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72  there are no err
32c0: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ors..**.** {F121
32d0: 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
32e0: 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 69 6f  _exec()] functio
32f0: 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  n sets the error
3300: 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
3310: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63  e.**          ac
3320: 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
3330: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3340: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3350: 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c  rmsg()]..**.** L
3360: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3370: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3380: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3390: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
33a0: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
33b0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
33c0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
33d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
33e0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
33f0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
3400: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3410: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3420: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3440: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20  running..** .** 
3450: 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {U12143} The cal
3460: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ling function is
3470: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
3480: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
3490: 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  free.**         
34a0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
34b0: 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74   *errmsg is left
34c0: 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63   pointing at onc
34d0: 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20  e the error.**  
34e0: 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20          message 
34f0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
3500: 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  ded..**.** {U121
3510: 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74  45} The SQL stat
3520: 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68  ement text in th
3530: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3540: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3550: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
3560: 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68  must remain unch
3570: 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c  anged while [sql
3580: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3590: 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
35a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
35b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
35c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
35e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
35f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
3600: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
3610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3620: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
3630: 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  uted */.  int (*
3640: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3650: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3660: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3670: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3680: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
36b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
36c0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
36d0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3700: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3710: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3720: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3730: 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20  des {F10210}.** 
3740: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3750: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3760: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3770: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
3780: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
3790: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
37a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
37b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
37c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
37d0: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
37e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
37f0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  .** See also: [S
3800: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3810: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
3820: 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65  lt codes].*/.#de
3830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
3840: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
3850: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
3860: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
3870: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
3880: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3890: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
38a0: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
38b0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
38c0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
38d0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
38e0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
38f0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
3900: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
3910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
3920: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
3930: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
3940: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
3950: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
3960: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
3970: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
3980: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
3990: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
39a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
39b0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
39c0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
39d0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
39e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
39f0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
3a00: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
3a10: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
3a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3a30: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
3a40: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
3a50: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
3a60: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
3a70: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
3a80: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
3a90: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
3aa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3ab0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
3ac0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
3ad0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
3ae0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
3af0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
3b00: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
3b10: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
3b20: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
3b30: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
3b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
3b50: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
3b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
3b70: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
3b80: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
3b90: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
3ba0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54  D    12   /* NOT
3bb0: 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20   USED. Table or 
3bc0: 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64  record not found
3bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3be0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
3bf0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
3c00: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
3c10: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
3c20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c30: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
3c40: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
3c50: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
3c60: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3c70: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
3c80: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f  OL    15   /* NO
3c90: 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65  T USED. Database
3ca0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
3cb0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
3cc0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
3cd0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
3ce0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
3cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
3d00: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
3d10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
3d20: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
3d30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3d40: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
3d50: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
3d60: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
3d70: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
3d80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
3d90: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
3da0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
3db0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
3dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3dd0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
3de0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
3df0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
3e00: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
3e10: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
3e20: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
3e30: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
3e40: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
3e50: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
3e60: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
3e70: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
3e80: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
3e90: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
3ea0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
3eb0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
3ee0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
3ef0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
3f00: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
3f10: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
3f20: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
3f30: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3f40: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
3f50: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
3f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
3f70: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
3f80: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
3f90: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
3fa0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3fb0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
3fc0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
3fd0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
3fe0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
3ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4000: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4010: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4020: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4030: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4040: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4050: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4060: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4070: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
4080: 31 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10220}.** KEYWOR
4090: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
40a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
40b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
40c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
40d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
40e0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
40f0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4100: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4110: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4120: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4130: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4140: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4150: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4160: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4170: 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e  hown that.** man
4180: 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c  y of these resul
4190: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
41a0: 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  course-grained. 
41b0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
41c0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
41d0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
41e0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
41f0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4200: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4210: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4220: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4230: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4240: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4250: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4260: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4270: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4280: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4290: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
42a0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
42b0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
42c0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
42d0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
42e0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
42f0: 6c 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20  led.** for each 
4300: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4310: 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ion using the [s
4320: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4330: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a  result_codes()].
4340: 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53  ** API..** .** S
4350: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ome of the avail
4360: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65  able extended re
4370: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c  sult codes are l
4380: 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f  isted here..** O
4390: 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68  ne may expect th
43a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65  e number of exte
43b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
43c0: 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64  s will be expand
43d0: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20  .** over time.  
43e0: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
43f0: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
4400: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
4410: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
4420: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
4430: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
4440: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
4450: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
4460: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
4470: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
4480: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
4490: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
44a0: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a  actly zero..** .
44b0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
44c0: 2a 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68  *.** {F10223} Th
44d0: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
44e0: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
44f0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61  result code alwa
4500: 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ys contains.**  
4510: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
4520: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
4530: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
4540: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34  x..**.** {F10224
4550: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
4560: 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74   code names cont
4570: 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22  ain a single "_"
4580: 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a   character..**.*
4590: 2a 20 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e  * {F10225} Exten
45a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
45b0: 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77  names contain tw
45c0: 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68  o or more "_" ch
45d0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
45e0: 7b 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d  {F10226} The num
45f0: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e  eric value of an
4600: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4610: 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74   code contains t
4620: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
4630: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20  umeric value of 
4640: 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  its correspondin
4650: 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  g primary result
4660: 20 63 6f 64 65 20 69 74 0a 2a 2a 20 20 20 20 20   code it.**     
4670: 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 73       its least s
4680: 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74  ignificant 8 bit
4690: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
46a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
46b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
46c0: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
46f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4700: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
4710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4720: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 28  _WRITE         (
4730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4740: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
4750: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
4760: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4770: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4790: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
47a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
47b0: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
47c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
47d0: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
47e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
47f0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
4800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
4810: 41 54 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AT         (SQLI
4820: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
4830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4840: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
4850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4860: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4880: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4890: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
48a0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
48b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
48c0: 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 51 4c  LETE        (SQL
48d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
48e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
48f0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
4900: 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  D       (SQLITE_
4910: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
4920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4930: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
4940: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4950: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a  R | (12<<8))../*
4960: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
4970: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
4980: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31  n Operations {F1
4990: 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0230}.**.** Thes
49a0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
49b0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
49c0: 65 20 69 6e 20 74 68 65 6e 0a 2a 2a 20 33 72 64  e in then.** 3rd
49d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
49e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
49f0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
4a00: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
4a10: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
4a20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
4a30: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
4a40: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
4a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a60: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
4a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4a80: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
4a90: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
4aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4ab0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
4ac0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
4ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4ae0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
4af0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
4b00: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
4b10: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
4b20: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
4b30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
4b40: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
4b50: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
4b60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
4b70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4b80: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
4b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
4ba0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4bb0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
4bc0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
4bd0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4be0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
4bf0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
4c00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
4c20: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
4c30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c40: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
4c50: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
4c60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
4c70: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
4c80: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
4c90: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
4ca0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
4cb0: 63 74 65 72 69 73 74 69 63 73 20 7b 46 31 30 32  cteristics {F102
4cc0: 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  40}.**.** The xD
4cd0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
4ce0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
4cf0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4d00: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
4d10: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
4d20: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
4d30: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
4d40: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
4d50: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
4d60: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
4d70: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
4d80: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
4d90: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
4da0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
4db0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
4dc0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
4dd0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
4de0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
4df0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
4e00: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
4e10: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
4e20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4e30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
4e40: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
4e50: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
4e60: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
4e70: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
4e80: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
4e90: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
4ea0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
4eb0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
4ec0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
4ed0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4ee0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
4ef0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
4f00: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
4f10: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
4f20: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
4f30: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
4f40: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
4f50: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
4f60: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
4f70: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
4f80: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
4f90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4fa0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
4fb0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
4fc0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
4fd0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
4fe0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
4ff0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5000: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5020: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
5030: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
5040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5050: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
5060: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5080: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5090: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
50b0: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
50c0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
50d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
50e0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
50f0: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5110: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5120: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5140: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5150: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
5160: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5170: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
5180: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5190: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
51a0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
51b0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
51c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
51d0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
51e0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5200: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5210: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
5220: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5230: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5240: 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F10250}.**.** 
5250: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
5260: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
5270: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5280: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
5290: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
52a0: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
52b0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
52c0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
52d0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
52e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
52f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5300: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
5310: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
5320: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5330: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
5340: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
5350: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
5360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5370: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
5380: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
5390: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
53a0: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
53b0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
53c0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
53d0: 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a  s {F10260}.**.**
53e0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
53f0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
5400: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
5410: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5420: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
5430: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
5440: 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 74 68 65  on of the.** the
5450: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
5460: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
5470: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
5480: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
5490: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
54a0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
54b0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
54c0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
54d0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
54e0: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
54f0: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
5500: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5510: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
5520: 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  hed. The SQLITE_
5530: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e  SYNC_NORMAL mean
5540: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72  s .** to use nor
5550: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
5560: 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54  ntics. The SQLIT
5570: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
5580: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
5590: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
55a0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
55b0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
55e0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
5600: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
5610: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
5620: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
5630: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
5640: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5650: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
5660: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b  en File Handle {
5670: 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e  F11110}.**.** An
5680: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5690: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
56a0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
56b0: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
56c0: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
56d0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
56e0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
56f0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
5700: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
5710: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
5720: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
5730: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
5740: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
5750: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
5760: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
5770: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
5780: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5790: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
57a0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
57b0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
57c0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
57d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
57e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
57f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
5800: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
5810: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
5820: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
5830: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5840: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
5850: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
5860: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
5870: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5880: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
5890: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
58a0: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31  ods Object {F111
58b0: 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  20}.**.** Every 
58c0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
58d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
58e0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f   xOpen method co
58f0: 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72  ntains a pointer
5900: 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e   to.** an instan
5910: 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 20 6f  ce of the this o
5920: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5930: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5940: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5950: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5960: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5970: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
5980: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
5990: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
59a0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
59b0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
59c0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
59d0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
59e0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
59f0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
5a00: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20  mal fsync()..*  
5a10: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
5a20: 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20  e is an.** OS-X 
5a30: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
5a40: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
5a50: 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62  _DATA flag may b
5a60: 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20  e ORed in to.** 
5a70: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
5a80: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
5a90: 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20  he file and not 
5aa0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
5ab0: 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e  to be.** synced.
5ac0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65  .** .** The inte
5ad0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
5ae0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5af0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
5b00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
5b10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5b30: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5b40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
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 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5b80: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
5b90: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5ba0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
5bb0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
5bc0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
5bd0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
5be0: 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54  the lock.  .** T
5bf0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5c00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c  dLock() method l
5c10: 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ooks.** to see i
5c20: 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  f any database c
5c30: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65  onnection, eithe
5c40: 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f  r in this.** pro
5c50: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
5c60: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
5c70: 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53  s holding an RES
5c80: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5c90: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5ca0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5cb0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5cc0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5cd0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5ce0: 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a  false if not..**
5cf0: 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f   .** The xFileCo
5d00: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
5d10: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
5d20: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
5d30: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
5d40: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5d50: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
5d60: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
5d70: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
5d80: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
5d90: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
5da0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
5db0: 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  p" argument.** i
5dc0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63  s an integer opc
5dd0: 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72 64  ode.   The third
5de0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
5df0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
5e00: 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e  r which is inten
5e10: 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e  ded to be a poin
5e20: 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75  ter.** to a stru
5e30: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
5e40: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
5e50: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
5e60: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
5e70: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
5e80: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
5e90: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
5ea0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
5eb0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
5ec0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
5ed0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
5ee0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
5ef0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
5f00: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
5f10: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
5f20: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
5f30: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
5f40: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
5f50: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
5f60: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
5f70: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
5f80: 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65  erves opcodes le
5f90: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
5fa0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a  its own use. .**
5fb0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
5fc0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
5fd0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
5fe0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
5ff0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6000: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6010: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6020: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6030: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6040: 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65  codes .** greate
6050: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6060: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6070: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
6080: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
6090: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
60a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
60b0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
60c0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
60d0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
60e0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
60f0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6100: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6110: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6120: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6130: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6140: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6150: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6160: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6170: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6180: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6190: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
61a0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
61b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
61c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
61d0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
61e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
61f0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6210: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <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 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <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 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <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 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <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 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
62a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
62b0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
62c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
62d0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
62e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
62f0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6300: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6310: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6320: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6560: 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  e()..*/.typedef 
6570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6580: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
6590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
65a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65b0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
65c0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
65d0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
65e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
65f0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6600: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6610: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6620: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6630: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6650: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6660: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6670: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
6680: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
6690: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
66a0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
66b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
66c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
66d0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
66e0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
66f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6710: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6720: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6730: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6740: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6760: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6770: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6780: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
6790: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
67a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
67b0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
67c0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
67d0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
67e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
67f0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6800: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6810: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6820: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6830: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6840: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6850: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6860: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
6870: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
6880: 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a  pcodes {F11310}.
6890: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
68a0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
68b0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
68c0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
68d0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
68e0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
68f0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
6900: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6910: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
6920: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
6930: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
6940: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
6950: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
6960: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
6970: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
6980: 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  ases the xFileCo
6990: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
69a0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
69b0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
69c0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
69d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
69e0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
69f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6a10: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
6a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
6a30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6a40: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
6a50: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
6a60: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
6a70: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
6a80: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
6a90: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
6aa0: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
6ab0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
6ac0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
6ad0: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
6ae0: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ned..*/.#define 
6af0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b00: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
6b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6b20: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46   Mutex Handle {F
6b30: 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17110}.**.** The
6b40: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
6b50: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
6b60: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
6b70: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
6b80: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
6b90: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
6ba0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
6bb0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
6bc0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
6bd0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
6be0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6bf0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
6c00: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
6c10: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
6c20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
6c30: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
6c40: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
6c50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
6c60: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
6c70: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
6c80: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
6c90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
6ca0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6cb0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
6cc0: 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a  ect {F11140}.**.
6cd0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
6ce0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
6cf0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
6d00: 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  ace between the.
6d10: 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  ** SQLite core a
6d20: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
6d30: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
6d40: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
6d50: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
6d60: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
6d70: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
6d80: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
6d90: 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e  .** The iVersion
6da0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
6db0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
6dc0: 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75   larger for futu
6dd0: 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
6de0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
6df0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
6e00: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
6e10: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
6e20: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
6e30: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
6e40: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
6e50: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
6e60: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6e70: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
6e80: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
6e90: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
6ea0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
6eb0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
6ec0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
6ed0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
6ee0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
6ef0: 52 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d  Registered vfs m
6f00: 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20  odules are kept 
6f10: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
6f20: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
6f30: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6f40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
6f50: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
6f60: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
6f70: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
6f80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
6f90: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
6fa0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
6fb0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
6fc0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
6fd0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
6fe0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a  rches the list..
6ff0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
7000: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
7010: 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20  y fields in the 
7020: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
7030: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7040: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7050: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7060: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7070: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7080: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7090: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
70a0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
70b0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
70c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
70d0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
70e0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
70f0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
7100: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7110: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7120: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7130: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7140: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7150: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7160: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7170: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7180: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7190: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
71a0: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
71b0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
71c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
71d0: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
71e0: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
71f0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
7200: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
7210: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
7220: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
7230: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
7240: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7250: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7260: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7270: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7280: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7290: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
72a0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
72b0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
72c0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
72d0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
72e0: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
72f0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
7300: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
7310: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7320: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7330: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7340: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7350: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7360: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7370: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7380: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7390: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
73a0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
73b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
73c0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
73d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
73e0: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
73f0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
7400: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
7410: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
7420: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
7430: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
7440: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7450: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7460: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7470: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7480: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7490: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
74a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
74b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
74c0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
74d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
74e0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
74f0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
7500: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7510: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
7520: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7530: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
7540: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7550: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7570: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7580: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7590: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
75a0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
75b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
75c0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
75d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
75e0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
75f0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
7600: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
7610: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
7620: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
7630: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
7640: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7650: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7660: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7670: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7680: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7690: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
76a0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
76b0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c 20  ry or rollback, 
76c0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
76d0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
76e0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
76f0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7700: 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a 2a  s journal are.**
7710: 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20   also a no-op.  
7720: 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  Any attempt to r
7730: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
7740: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4f  return SQLITE_IO
7750: 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20 69  ERR..** Or the i
7760: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
7770: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
7780: 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  e a database fil
7790: 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69  e will.** be doi
77a0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
77b0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
77c0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
77d0: 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e 64  dom order.** and
77e0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
77f0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
7800: 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ingly..** .** SQ
7810: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
7820: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
7830: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
7840: 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d  o the xOpen.** m
7850: 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ethod:.** .** <u
7860: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7870: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7880: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
7890: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
78a0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
78b0: 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20  ** .** {F11145} 
78c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
78d0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
78e0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
78f0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7900: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7910: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31   is closed.  {F1
7920: 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54  1146} The [SQLIT
7930: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7940: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
7950: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
7960: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
7970: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
7980: 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31 31  urnals. .** {F11
7990: 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  147} The [SQLITE
79a0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
79b0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
79c0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
79d0: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
79e0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
79f0: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
7a00: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
7a10: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
7a20: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
7a30: 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ile. {END}.** .*
7a40: 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c 65  * {F11148} At le
7a50: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
7a60: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 69 73 20  es of memory is 
7a70: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
7a80: 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  ite .** to hold 
7a90: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
7aa0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
7ab0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
7ac0: 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  d .** argument t
7ad0: 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44 7d 20  o xOpen.  {END} 
7ae0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
7af0: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
7b00: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
7b10: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
7b20: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
7b30: 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a 2a 20  l it in..** .** 
7b40: 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 6c 61  {F11149} The fla
7b50: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7b60: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
7b70: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
7b80: 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65  XISTS] .** to te
7b90: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
7ba0: 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a  ance of a file,.
7bb0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  ** or [SQLITE_AC
7bc0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
7bd0: 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a 2a  to test to see.*
7be0: 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72  * if a file is r
7bf0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
7c00: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
7c10: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
7c20: 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 20   to test to see 
7c30: 69 66 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  if a file is at 
7c40: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
7c50: 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65 20   {END} The file 
7c60: 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72  can be a .** dir
7c70: 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 7b  ectory..** .** {
7c80: 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77  F11150} SQLite w
7c90: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
7ca0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
7cb0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66  athname+1 byte f
7cc0: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74  or.** the output
7cd0: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65   buffers for xGe
7ce0: 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 78 46  tTempname and xF
7cf0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31  ullPathname. {F1
7d00: 31 31 35 31 7d 20 54 68 65 20 65 78 61 63 74 0a  1151} The exact.
7d10: 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ** size of the o
7d20: 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20  utput buffer is 
7d30: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
7d40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
7d50: 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20  th .** methods. 
7d60: 7b 45 4e 44 7d 20 49 66 20 74 68 65 20 6f 75 74  {END} If the out
7d70: 70 75 74 20 62 75 66 66 65 72 20 69 73 20 6e 6f  put buffer is no
7d80: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
7d90: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 0a  SQLITE_CANTOPEN.
7da0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
7db0: 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69  urned. As this i
7dc0: 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  s handled as a f
7dd0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
7de0: 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70  Lite,.** vfs imp
7df0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
7e00: 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20  uld endeavor to 
7e10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
7e20: 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61  setting .** mxPa
7e30: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
7e40: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
7e50: 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  alue..** .** The
7e60: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
7e70: 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43  xSleep(), and xC
7e80: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74  urrentTime() int
7e90: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
7ea0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
7eb0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
7ec0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
7ed0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
7ee0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
7ef0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
7f00: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
7f10: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
7f20: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
7f30: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
7f40: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
7f50: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
7f60: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
7f70: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
7f80: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
7f90: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
7fa0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
7fb0: 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  tained.  The.** 
7fc0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
7fd0: 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69 6e  cause the callin
7fe0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
7ff0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
8000: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
8010: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
8020: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
8030: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
8040: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
8050: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
8060: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
8070: 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a  te and.** time..
8080: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8090: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
80a0: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
80b0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
80c0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
80d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
80e0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
80f0: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
8100: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
8110: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
8120: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
8130: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
8140: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
8150: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
8160: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
8170: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
8180: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
8190: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
81a0: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
81b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
81c0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
81d0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
81e0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
81f0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
8200: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
8210: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
8220: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
8230: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
8240: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8250: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8260: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
8270: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
8280: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
8290: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
82a0: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
82b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
82c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
82d0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
82e0: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
82f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8300: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8310: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8320: 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 6e 61  int (*xGetTempna
8330: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8340: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
8350: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
8360: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
8370: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8380: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8390: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
83a0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
83b0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
83c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
83d0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
83e0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
83f0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
8400: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
8410: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
8420: 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73  oid *(*xDlSym)(s
8430: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
8440: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8450: 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20  Symbol);.  void 
8460: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
8470: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
8480: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
8490: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
84a0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
84b0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
84c0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
84d0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
84e0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
84f0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
8500: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8510: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a  , double*);.  /*
8520: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
8530: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
8540: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
8550: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
8560: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
8570: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
8580: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a   this happens. *
8590: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
85a0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
85b0: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
85c0: 6d 65 74 68 6f 64 20 7b 46 31 31 31 39 30 7d 0a  method {F11190}.
85d0: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31 7d 20 54  **.** {F11191} T
85e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
85f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
8600: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
8610: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8620: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8630: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
8640: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b  3_vfs] object. {
8650: 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 72  END}  They deter
8660: 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64  mine.** the kind
8670: 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66   of what kind of
8680: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
8690: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
86a0: 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f  is.** looking fo
86b0: 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74  r.  {F11192} Wit
86c0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
86d0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
86e0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
86f0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8700: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8710: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8720: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8730: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8740: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8750: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8760: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
8770: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8780: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
8790: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
87a0: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
87b0: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
87c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
87d0: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
87e0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
87f0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8800: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8810: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8820: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8830: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8840: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8850: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8860: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
8870: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
8880: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
8890: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
88a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
88b0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
88c0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
88d0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
88e0: 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  es the.** [SQLIT
88f0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
8900: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
8910: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
8920: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20   SQLite..** The 
8930: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8940: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
8950: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
8960: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
8970: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
8980: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
8990: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20  .**.** {F12201} 
89a0: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
89b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
89c0: 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  as the .**      
89d0: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65      [extended re
89e0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
89f0: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
8a00: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
8a10: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
8a20: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
8a30: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
8a40: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
8a50: 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61 62  erface will enab
8a60: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8a70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8a80: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8a90: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8aa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8ab0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8ac0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8ad0: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8ae0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8af0: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8b00: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8b10: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8b20: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8b30: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8b40: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8b50: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8b60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8b70: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8b80: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8b90: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8ba0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8bb0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8bc0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8bd0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8be0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8bf0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8c00: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8c10: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8c20: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8c30: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8c40: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8c50: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8c60: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8c70: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8c80: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8c90: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8ca0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8cb0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e  ** is another an
8cc0: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
8cd0: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
8ce0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8cf0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
8d00: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
8d10: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
8d20: 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  RT into the data
8d30: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
8d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8d50: 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68  n.** shown in th
8d60: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
8d70: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
8d80: 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68  ful inserts.** h
8d90: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
8da0: 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61  d on this databa
8db0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
8dc0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
8dd0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
8de0: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
8df0: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
8e00: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
8e10: 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72  he.** inserted r
8e20: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
8e30: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
8e40: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
8e50: 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e  igger.** is runn
8e60: 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74  ing.  But once t
8e70: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
8e80: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
8e90: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
8ea0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
8eb0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
8ec0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
8ed0: 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72  before the.** tr
8ee0: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
8ef0: 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61  ** An INSERT tha
8f00: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
8f10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
8f20: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
8f30: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73  * successful ins
8f40: 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ert and does not
8f50: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
8f60: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
8f70: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
8f80: 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
8f90: 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
8fa0: 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
8fb0: 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
8fc0: 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
8fd0: 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
8fe0: 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
8ff0: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
9000: 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
9010: 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
9020: 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52  ils.  When INSER
9030: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a  T OR REPLACE .**
9040: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
9050: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
9060: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
9070: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
9080: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
9090: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
90a0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
90b0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
90c0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
90d0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
90e0: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
90f0: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
9100: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
9110: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
9120: 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72  face. .**.** For
9130: 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
9140: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
9150: 6e 20 69 6e 73 65 72 74 20 69 73 20 63 6f 6e 73  n insert is cons
9160: 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
9170: 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
9180: 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
9190: 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
91a0: 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  k..**.** INVARIA
91b0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
91c0: 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
91d0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
91e0: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
91f0: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
9200: 20 20 20 20 20 20 20 72 6f 77 69 64 20 6f 66 20         rowid of 
9210: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
9220: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72  successful inser
9230: 74 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20  t done.**       
9240: 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64     on the same d
9250: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9260: 6f 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  on and within th
9270: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
9280: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
9290: 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
92a0: 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20  here have.**    
92b0: 20 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 71 75        been no qu
92c0: 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73  alifying inserts
92d0: 20 6f 6e 20 74 68 61 74 20 63 6f 6e 6e 65 63 74   on that connect
92e0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ion..**.** {F122
92f0: 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
9300: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
9310: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
9320: 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
9330: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
9340: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
9350: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
9360: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
9370: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
9380: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
9390: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
93a0: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
93b0: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49  **.** {U12232} I
93c0: 66 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  f separate threa
93d0: 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73  d does a new ins
93e0: 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  ert on the same.
93f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
9400: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9410: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
9420: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
9430: 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20  owid()].**      
9440: 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20      function is 
9450: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
9460: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
9470: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a  t insert rowid,.
9480: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
9490: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
94a0: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
94b0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
94c0: 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  d()] is.**      
94d0: 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c      unpredictabl
94e0: 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
94f0: 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
9500: 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
9510: 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74  **          last
9520: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a   insert rowid..*
9530: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
9540: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
9550: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
9560: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
9570: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
9580: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
9590: 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d  odified {F12240}
95a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
95b0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
95c0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
95d0: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
95e0: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
95f0: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
9600: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
9610: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
9620: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
9630: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e  t.** on the conn
9640: 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
9650: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
9660: 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a  rameter.  Only.*
9670: 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  * changes that a
9680: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
9690: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
96a0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a  ERT, UPDATE, or.
96b0: 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
96c0: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
96d0: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
96e0: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
96f0: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
9700: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
9710: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
9720: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
9730: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
9740: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
9750: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
9760: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
9770: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
9780: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  s..**.** A "row 
9790: 63 68 61 6e 67 65 73 22 20 69 73 20 61 20 63 68  changes" is a ch
97a0: 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
97b0: 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
97c0: 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
97d0: 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
97e0: 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
97f0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
9800: 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
9810: 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
9820: 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45  fects of REPLACE
9830: 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
9840: 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
9850: 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
9860: 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c  ssing, DROP TABL
9870: 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  E, or by any oth
9880: 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
9890: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
98a0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
98b0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
98c0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
98d0: 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
98e0: 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
98f0: 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
9900: 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
9910: 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f  f a trigger.  Mo
9920: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
9930: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
9940: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
9950: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
9960: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
9970: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
9980: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
9990: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
99a0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
99b0: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
99c0: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
99d0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
99e0: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
99f0: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
9a00: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
9a10: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
9a20: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
9a30: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b  .**.** Calling [
9a40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
9a50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
9a60: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
9a70: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
9a80: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
9a90: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
9aa0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
9ab0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
9ac0: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
9ad0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
9ae0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
9af0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
9b00: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
9b10: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9b20: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
9b30: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68  ext..**.** So wh
9b40: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
9b50: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
9b60: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
9b70: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
9b80: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
9b90: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
9ba0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
9bb0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
9bc0: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
9bd0: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
9be0: 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20  ..** Within the 
9bf0: 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
9c00: 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  r, the sqlite3_c
9c10: 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
9c20: 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c  ce.** can be cal
9c30: 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
9c40: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
9c50: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
9c60: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
9c70: 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
9c80: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
9c90: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
9ca0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
9cb0: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
9cc0: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
9cd0: 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
9ce0: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
9cf0: 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63   in changes.** c
9d00: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
9d10: 67 65 72 73 20 73 69 6e 63 65 20 74 68 65 79 20  gers since they 
9d20: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
9d30: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
9d40: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
9d50: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
9d60: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
9d70: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
9d80: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
9d90: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
9da0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
9db0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
9dc0: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
9dd0: 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e 64 20  ing through and 
9de0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
9df0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
9e00: 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29  m the.** table.)
9e10: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
9e20: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
9e30: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
9e40: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
9e50: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
9e60: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 20  row changes and 
9e70: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
9e80: 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 73 71  ted.** by the sq
9e90: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
9ea0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
9eb0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
9ec0: 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65  ctions..** To ge
9ed0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
9ee0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
9ef0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
9f00: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
9f10: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
9f20: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
9f30: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
9f40: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20  .**.** {F12241} 
9f50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  The [sqlite3_cha
9f60: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
9f70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
9f80: 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
9f90: 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63     row changes c
9fa0: 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73  aused by the mos
9fb0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
9fc0: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20   UPDATE,.**     
9fd0: 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73       or DELETE s
9fe0: 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
9ff0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
a000: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  nnection and.** 
a010: 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e 20           within 
a020: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
a030: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
a040: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
a050: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  **          not 
a060: 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79  been any qualify
a070: 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ing row changes.
a080: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
a090: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35  NS:.**.** {U1225
a0a0: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
a0b0: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
a0c0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
a0d0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
a0e0: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
a0f0: 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33    while [sqlite3
a100: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
a110: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
a120: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
a130: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
a140: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
a150: 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  unmeaningful..*/
a160: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
a170: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
a180: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a190: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
a1a0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
a1b0: 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54  F12260}.***.** T
a1c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
a1d0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
a1e0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
a1f0: 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45  aused.** by INSE
a200: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
a210: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
a220: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
a230: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
a240: 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f   opened.  The co
a250: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
a260: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
a270: 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e  l trigger.** con
a280: 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 65 20  texts.  But the 
a290: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
a2a0: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
a2b0: 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d  sed to.** implem
a2c0: 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73  ent REPLACE cons
a2d0: 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c  traints, do roll
a2e0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
a2f0: 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72  rocessing,.** or
a300: 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63   DROP table proc
a310: 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63  essing..** The c
a320: 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f  hanges.** are co
a330: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
a340: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
a350: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
a360: 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20  s completed .** 
a370: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
a380: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
a390: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
a3a0: 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a  _reset()] or .**
a3b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
a3c0: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
a3d0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
a3e0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
a3f0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
a400: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
a410: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
a420: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
a430: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
a440: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
a450: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
a460: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
a470: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
a480: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
a490: 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  form the table.)
a4a0: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
a4b0: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
a4c0: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
a4d0: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
a4e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
a4f0: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
a500: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
a510: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
a520: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
a530: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
a540: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
a550: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
a560: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
a570: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
a580: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
a590: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
a5a0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
a5b0: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
a5c0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a5d0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
a5e0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
a5f0: 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  * .** {F12261} T
a600: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
a610: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
a620: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
a630: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
a640: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
a650: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
a660: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
a670: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
a680: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
a690: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
a6a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a6b0: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
a6c0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
a6d0: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
a6e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a6f0: 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20  tion was.**     
a700: 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a       created..**
a710: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
a720: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20  .**.** {U12264} 
a730: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
a740: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
a750: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
a760: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a770: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
a780: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
a790: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
a7a0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
a7b0: 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20  he value .**    
a7c0: 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
a7d0: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
a7e0: 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c  and unmeaningful
a7f0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a800: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
a810: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
a820: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
a830: 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
a840: 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32 37  ing Query {F1227
a850: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
a860: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
a870: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
a880: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
a890: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
a8a0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
a8b0: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
a8c0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
a8d0: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
a8e0: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
a8f0: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
a900: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
a910: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
a920: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
a930: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
a940: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
a950: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
a960: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
a970: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
a980: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
a990: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
a9a0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
a9b0: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
a9c0: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
a9d0: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
a9e0: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
a9f0: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
aa00: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
aa10: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
aa20: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
aa30: 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69  ection that.** i
aa40: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
aa50: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
aa60: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
aa70: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
aa80: 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76  * If an SQL is v
aa90: 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
aaa0: 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
aab0: 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74  when sqlite3_int
aac0: 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63  errupt().** is c
aad0: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
aae0: 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
aaf0: 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20   opportunity to 
ab00: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a  be interrupted..
ab10: 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74  ** It might cont
ab20: 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
ab30: 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  on..** An SQL op
ab40: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
ab50: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
ab60: 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
ab70: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20 20  TE_INTERRUPT].  
ab80: 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
ab90: 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
aba0: 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54   is an.** INSERT
abb0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
abc0: 45 54 45 20 74 68 61 74 20 69 73 20 69 6e 73 69  ETE that is insi
abd0: 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
abe0: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20  ransaction, .** 
abf0: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
ac00: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c  transaction will
ac10: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
ac20: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
ac30: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ac40: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ac50: 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
ac60: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
ac70: 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
ac80: 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
ac90: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
aca0: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
acb0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
acc0: 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  F12271} The [sql
acd0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ace0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
acf0: 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
ad00: 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
ad10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
ad20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
ad30: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
ad40: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
ad50: 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
ad60: 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
ad70: 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
ad80: 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a  tional row of.**
ad90: 20 20 20 20 20 20 20 20 20 20 64 61 74 61 2e 0a            data..
ada0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41  **.** {F12272} A
adb0: 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
adc0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
add0: 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
ade0: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
adf0: 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
ae00: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
ae10: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
ae20: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
ae30: 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74  ** {U12279} If t
ae40: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
ae50: 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
ae60: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
ae70: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
ae80: 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
ae90: 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
aea0: 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
aeb0: 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
aec0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
aed0: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
aee0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
aef0: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
af00: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
af10: 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a  lete {F10510}.**
af20: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
af30: 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  es are useful fo
af40: 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  r command-line i
af50: 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
af60: 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
af70: 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
af80: 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
af90: 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20   complete a SQL 
afa0: 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
afb0: 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
afc0: 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
afd0: 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
afe0: 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
aff0: 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
b000: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
b010: 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  s return true if
b020: 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
b030: 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
b040: 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
b050: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20  L statement.  A 
b060: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
b070: 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
b080: 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
b090: 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
b0a0: 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
b0b0: 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66  ot a fragment of
b0c0: 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49   a.** CREATE TRI
b0d0: 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
b0e0: 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74   Semicolons that
b0f0: 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
b100: 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
b110: 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
b120: 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
b130: 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
b140: 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
b150: 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
b160: 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
b170: 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
b180: 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
b190: 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
b1a0: 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
b1b0: 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
b1c0: 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
b1d0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
b1e0: 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
b1f0: 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c  QL and.** so wil
b200: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
b210: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
b220: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
b230: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
b240: 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73  * {F10511} The s
b250: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
b260: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
b270: 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74  mplete16() funct
b280: 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ions.**         
b290: 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   return true (no
b2a0: 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f  n-zero) if and o
b2b0: 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 0a  nly if the last.
b2c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d  **          non-
b2d0: 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e  whitespace token
b2e0: 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20   in their input 
b2f0: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  is a semicolon t
b300: 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
b310: 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
b320: 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20  n the BEGIN and 
b330: 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20  END of a CREATE 
b340: 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20 20 20  TRIGGER.**      
b350: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
b360: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
b370: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d  :.**.** {U10512}
b380: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71   The input to sq
b390: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
b3a0: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
b3b0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
b3c0: 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
b3d0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35  ing..**.** {U105
b3e0: 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
b3f0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
b400: 65 31 36 28 29 20 6d 75 73 74 20 62 65 20 61 20  e16() must be a 
b410: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
b420: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
b430: 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
b440: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
b450: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
b460: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
b470: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
b480: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
b490: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
b4a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b4b0: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
b4c0: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
b4d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
b4e0: 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a  rors {F12310}.**
b4f0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
b500: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
b510: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
b520: 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a  that might be.**
b530: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
b540: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
b550: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
b560: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
b570: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
b580: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
b590: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
b5a0: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
b5b0: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
b5c0: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
b5d0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
b5e0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
b5f0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
b600: 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
b610: 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
b620: 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62  ock..** If the b
b630: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
b640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
b650: 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77  he.** callback w
b660: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
b670: 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
b680: 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74  s.  The.** first
b690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b6a0: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
b6b0: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
b6c0: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
b6d0: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
b6e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72  gument to this r
b6f0: 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63  outine.  The sec
b700: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
b710: 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  ** the handler i
b720: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
b730: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
b740: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
b750: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
b760: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
b770: 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74 68 65   event.   If the
b780: 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
b790: 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
b7a0: 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
b7b0: 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
b7c0: 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
b7d0: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
b7e0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
b7f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
b800: 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
b810: 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
b820: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
b830: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
b840: 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
b850: 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
b860: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b870: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
b880: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
b890: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
b8a0: 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
b8b0: 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
b8c0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a  guarantee that.*
b8d0: 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  * it will be inv
b8e0: 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20  oked when there 
b8f0: 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
b900: 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  on..** If SQLite
b910: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
b920: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
b930: 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  sy handler could
b940: 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20   result in.** a 
b950: 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
b960: 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
b970: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
b980: 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  SY] or.** [SQLIT
b990: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
b9a0: 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
b9b0: 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79  king the.** busy
b9c0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
b9d0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
b9e0: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
b9f0: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
ba00: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
ba10: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
ba20: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
ba30: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
ba40: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
ba50: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
ba60: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
ba70: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
ba80: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
ba90: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
baa0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
bab0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
bac0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
bad0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
bae0: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
baf0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
bb00: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
bb10: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
bb20: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
bb30: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
bb40: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
bb50: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
bb60: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
bb70: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
bb80: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
bb90: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
bba0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
bbb0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
bbc0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
bbd0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
bbe0: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
bbf0: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
bc00: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
bc10: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
bc20: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
bc30: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
bc40: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
bc50: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
bc60: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
bc70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
bc80: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
bc90: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
bca0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
bcb0: 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
bcc0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
bcd0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
bce0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
bcf0: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
bd00: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
bd10: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
bd20: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
bd30: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
bd40: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
bd50: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
bd60: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
bd70: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
bd80: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
bd90: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
bda0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
bdb0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
bdc0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
bdd0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
bde0: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
bdf0: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
be00: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
be10: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
be20: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
be30: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
be40: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
be50: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
be60: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
be70: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
be80: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
be90: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
bea0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
beb0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
bec0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
bed0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
bee0: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
bef0: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
bf00: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
bf10: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
bf20: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
bf30: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
bf40: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
bf50: 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74  .sqlite.org/cvst
bf60: 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
bf70: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
bf80: 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
bf90: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
bfa0: 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
bfb0: 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
bfc0: 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
bfd0: 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
bfe0: 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65  tant..**..** The
bff0: 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
c000: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
c010: 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
c020: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a   each database.*
c030: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
c040: 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
c050: 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
c060: 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e   any previous on
c070: 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  e. .** Note that
c080: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
c090: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
c0a0: 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  ] will also set 
c0b0: 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20  or clear.** the 
c0c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
c0d0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
c0e0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54  **.** {F12311} T
c0f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
c100: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63  _handler()] func
c110: 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
c120: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  e busy handler.*
c130: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
c140: 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62  ack in the datab
c150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
c160: 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
c170: 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   1st.**         
c180: 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
c190: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
c1a0: 65 72 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  er identified by
c1b0: 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64   the 2nd and 3rd
c1c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
c1d0: 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ameters..**.** {
c1e0: 46 31 32 33 31 32 7d 20 54 68 65 20 64 65 66 61  F12312} The defa
c1f0: 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  ult busy handler
c200: 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73   for new databas
c210: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73  e connections is
c220: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   NULL..**.** {F1
c230: 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f  2314} When two o
c240: 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20  r more database 
c250: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65  connection share
c260: 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c   a common cache,
c270: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
c280: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
c290: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
c2a0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
c2b0: 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
c2c0: 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
c2d0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
c2e0: 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e  the cache encoun
c2f0: 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a  ters a lock..**.
c300: 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61  ** {F12316} If a
c310: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
c320: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a  llback returns z
c330: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ero, then the SQ
c340: 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  Lite.**         
c350: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
c360: 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63  provoked the loc
c370: 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20  king event will 
c380: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
c390: 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d     [SQLITE_BUSY]
c3a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d  ..**.** {F12318}
c3b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
c3c0: 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68 61  okes the busy ha
c3d0: 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61  ndler with two a
c3e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
c3f0: 20 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20            are a 
c400: 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e  copy of the poin
c410: 74 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20  ter supplied by 
c420: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
c430: 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
c440: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
c450: 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20  andler()] and a 
c460: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
c470: 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20  ber of prior.** 
c480: 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
c490: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79  ions of the busy
c4a0: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
c4b0: 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
c4c0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
c4d0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
c4e0: 31 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61  12319} A busy ha
c4f0: 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74  ndler should not
c500: 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20   call close the 
c510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c520: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
c530: 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 61 74  or prepared stat
c540: 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b  ement that invok
c550: 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
c560: 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
c570: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c580: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
c590: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
c5a0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
c5b0: 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
c5c0: 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34  y Timeout {F1234
c5d0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
c5e0: 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
c5f0: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
c600: 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
c610: 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70  r].** that sleep
c620: 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68  s for a while wh
c630: 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73  en a.** table is
c640: 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
c650: 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70  ndler will sleep
c660: 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
c670: 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61  until .** at lea
c680: 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
c690: 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
c6a0: 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e   have been done.
c6b0: 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a   {F12343} After.
c6c0: 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  ** "ms" millisec
c6d0: 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
c6e0: 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  , the handler re
c6f0: 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a  turns 0 which.**
c700: 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
c710: 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
c720: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
c730: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
c740: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
c750: 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
c760: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
c770: 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
c780: 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
c790: 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
c7a0: 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
c7b0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
c7c0: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
c7d0: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
c7e0: 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
c7f0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
c800: 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e  nnection.  If an
c810: 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
c820: 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  er was defined  
c830: 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  .** (using [sqli
c840: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c850: 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
c860: 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
c870: 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
c880: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
c890: 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a  s cleared..**.**
c8a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
c8b0: 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20  ** {F12341} The 
c8c0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
c8d0: 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f  meout()] functio
c8e0: 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  n overrides any 
c8f0: 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
c900: 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
c910: 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
c920: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c930: 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
c940: 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
c950: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
c960: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
c970: 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68  * {F12343} If th
c980: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
c990: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
c9a0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
c9b0: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
c9c0: 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
c9d0: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
c9e0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
c9f0: 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a  cleared so that.
ca00: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20  **          all 
ca10: 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69  subsequent locki
ca20: 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69  ng events immedi
ca30: 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51  ately return [SQ
ca40: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
ca50: 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68  * {F12344} If th
ca60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
ca70: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
ca80: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61  _timeout()] is a
ca90: 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20   positive.**    
caa0: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20        number N, 
cab0: 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64  then a busy hand
cac0: 6c 65 72 20 69 73 20 73 65 74 20 74 68 61 74 20  ler is set that 
cad0: 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73  repeatedly calls
cae0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
caf0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
cb00: 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65   in the VFS inte
cb10: 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68  rface until eith
cb20: 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  er the.**       
cb30: 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f     lock clears o
cb40: 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75  r until the cumu
cb50: 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d  lative sleep tim
cb60: 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a  e reported back.
cb70: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 78  **          by x
cb80: 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20  Sleep() exceeds 
cb90: 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  N milliseconds..
cba0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
cbb0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
cbc0: 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
cbd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cbe0: 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
cbf0: 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
cc00: 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 37 30   Queries {F12370
cc10: 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  }.**.** Definiti
cc20: 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
cc30: 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
cc40: 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
cc50: 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
cc60: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
cc70: 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
cc80: 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
cc90: 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
cca0: 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
ccb0: 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
ccc0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
ccd0: 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
cce0: 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
ccf0: 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
cd00: 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
cd10: 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
cd20: 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
cd30: 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
cd40: 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
cd50: 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
cd60: 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
cd70: 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
cd80: 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
cd90: 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
cda0: 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
cdb0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
cdc0: 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
cdd0: 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
cde0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
cdf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
ce00: 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  * UTF-8 strings.
ce10: 20 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31    There are (N+1
ce20: 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
ce30: 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20  the array.  .** 
ce40: 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
ce50: 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65  ters point to ze
ce60: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
ce70: 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63  rings that .** c
ce80: 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
ce90: 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
cea0: 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
ceb0: 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
cec0: 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
ced0: 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76  ults.  NULL.** v
cee0: 61 6c 75 65 73 20 61 72 65 20 67 69 76 65 20 61  alues are give a
cef0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
cf00: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
cf10: 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72   are in.** their
cf20: 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
cf30: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 72 65  inated string re
cf40: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
cf50: 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
cf60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
cf70: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
cf80: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
cf90: 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f  ht consists of o
cfa0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
cfb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
cfc0: 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
cfd0: 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
cfe0: 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
cff0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
d000: 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
d010: 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
d020: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
d030: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
d040: 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
d050: 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
d060: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
d070: 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
d080: 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
d090: 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
d0a0: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
d0b0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
d0c0: 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
d0d0: 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
d0e0: 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
d0f0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
d100: 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
d110: 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
d120: 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
d130: 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
d140: 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
d150: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
d160: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
d170: 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
d180: 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
d190: 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
d1a0: 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
d1b0: 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
d1c0: 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
d1d0: 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
d1e0: 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
d1f0: 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
d200: 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
d210: 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
d220: 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
d230: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
d240: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
d250: 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
d260: 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
d270: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
d280: 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
d290: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d2a0: 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
d2b0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d2c0: 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
d2d0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d2e0: 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
d2f0: 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
d300: 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
d310: 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
d320: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
d330: 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
d340: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d350: 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
d360: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
d370: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te>.**.** The sq
d380: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d390: 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
d3a0: 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
d3b0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
d3c0: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
d3d0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
d3e0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
d3f0: 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
d400: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
d410: 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  er.  It returns 
d420: 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
d430: 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
d440: 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
d450: 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
d460: 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c  ** After the cal
d470: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61  ling function ha
d480: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
d490: 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20   the result, it 
d4a0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20  should .** pass 
d4b0: 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
d4c0: 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
d4d0: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
d4e0: 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
d4f0: 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20   to .** release 
d500: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
d510: 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20  was malloc-ed.  
d520: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
d530: 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ay the .** [sqli
d540: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
d550: 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
d560: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d570: 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
d580: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
d590: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
d5a0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
d5b0: 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20  directly.  Only 
d5c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
d5d0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
d5e0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
d5f0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
d600: 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
d610: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d620: 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
d630: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
d640: 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
d650: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
d660: 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
d670: 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
d680: 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
d690: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
d6a0: 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
d6b0: 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
d6c0: 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
d6d0: 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
d6e0: 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
d6f0: 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
d700: 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
d710: 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
d720: 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
d730: 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
d740: 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
d750: 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
d760: 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
d770: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
d780: 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
d790: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
d7a0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
d7b0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
d7c0: 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
d7d0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
d7e0: 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61  ** {F12371} If a
d7f0: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
d800: 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d  ble()] fails a m
d810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d820: 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
d830: 20 20 20 69 74 20 66 72 65 65 73 20 74 68 65 20     it frees the 
d840: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64  result table und
d850: 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c  er construction,
d860: 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20   aborts the.**  
d870: 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e          query in
d880: 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20   process, skips 
d890: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
d8a0: 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 68 65  ueries, sets the
d8b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65  .**          *re
d8c0: 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69  sultp output poi
d8d0: 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64  nter to NULL and
d8e0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
d8f0: 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
d900: 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e  F12373} If the n
d910: 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72  column parameter
d920: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
d930: 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
d940: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
d950: 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
d960: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
d970: 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
d980: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
d990: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
d9a0: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
d9b0: 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d  ery into *ncolum
d9c0: 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 20 69  n if the query i
d9d0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75  s.**          su
d9e0: 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68 65  ccessful (if the
d9f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
da00: 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a  s SQLITE_OK)..**
da10: 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 66 20  .** {F12374} If 
da20: 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d 65 74  the nrow paramet
da30: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
da40: 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
da50: 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
da60: 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
da70: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77  3_get_table()] w
da80: 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
da90: 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a  of rows in the.*
daa0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
dab0: 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
dac0: 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66  ry into *nrow if
dad0: 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a   the query is.**
dae0: 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73            succes
daf0: 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e  sful (if the fun
db00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51  ction returns SQ
db10: 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK)..**.** 
db20: 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71  {F12376} The [sq
db30: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
db40: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  )] function sets
db50: 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61   its *ncolumn va
db60: 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
db70: 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
db80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
db90: 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
dba0: 65 20 71 75 65 72 79 20 69 6e 20 74 68 65 0a 2a  e query in the.*
dbb0: 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 20 70  *          sql p
dbc0: 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20  arameter, or to 
dbd0: 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75 65 72  zero if the quer
dbe0: 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20  y in sql has an 
dbf0: 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20  empty.**        
dc00: 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f    result set..*/
dc10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
dc20: 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
dc30: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
dc40: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
dc50: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
dc60: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f  har *sql,      /
dc70: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
dc80: 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
dc90: 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20  ***pResult,     
dca0: 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
dcb0: 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
dcc0: 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20  t *nrow,        
dcd0: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
dce0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
dcf0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
dd00: 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20  nt *ncolumn,    
dd10: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
dd20: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
dd30: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
dd40: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
dd50: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
dd60: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
dd70: 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
dd80: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
dd90: 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
dda0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ddb0: 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
ddc0: 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
ddd0: 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a  tions {F17400}.*
dde0: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
ddf0: 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b  nes are workalik
de00: 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
de10: 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
de20: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
de30: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
de40: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  library..**.** T
de50: 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
de60: 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
de70: 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
de80: 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
de90: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
dea0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
deb0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
dec0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
ded0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
dee0: 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
def0: 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
df00: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
df10: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
df20: 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e  ].   Both routin
df30: 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
df40: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
df50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
df60: 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
df70: 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
df80: 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
df90: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
dfa0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  tring..**.** In 
dfb0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
dfc0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
dfd0: 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
dfe0: 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
dff0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
e000: 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
e010: 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
e020: 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
e030: 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
e040: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
e050: 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
e060: 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
e070: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
e080: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
e090: 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
e0a0: 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
e0b0: 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
e0c0: 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20  rom snprintf(). 
e0d0: 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
e0e0: 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
e0f0: 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
e100: 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
e110: 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
e120: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
e130: 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ity.  Note also 
e140: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
e150: 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
e160: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
e170: 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
e180: 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
e190: 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
e1a0: 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
e1b0: 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
e1c0: 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68  er.  We admit th
e1d0: 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
e1e0: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
e1f0: 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
e200: 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
e210: 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
e220: 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
e230: 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
e240: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
e250: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
e260: 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
e270: 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
e280: 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67  y..**.** As long
e290: 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
e2a0: 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
e2b0: 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
e2c0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
e2d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
e2e0: 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
e2f0: 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
e300: 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74  ated.  The first
e310: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
e320: 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
e330: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
e340: 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
e350: 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
e360: 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
e370: 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
e380: 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
e390: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
e3a0: 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
e3b0: 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
e3c0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
e3d0: 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
e3e0: 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
e3f0: 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
e400: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
e410: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
e420: 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
e430: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
e440: 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
e450: 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20  intf formatting 
e460: 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
e470: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
e480: 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
e490: 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
e4a0: 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
e4b0: 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
e4c0: 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
e4d0: 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
e4e0: 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
e4f0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
e500: 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
e510: 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
e520: 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
e530: 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
e540: 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
e550: 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
e560: 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
e570: 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
e580: 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
e590: 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
e5a0: 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
e5b0: 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
e5c0: 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
e5d0: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
e5e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
e5f0: 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20  xample, so some 
e600: 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
e610: 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
e620: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
e630: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e640: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
e650: 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
e660: 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
e670: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
e680: 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
e690: 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
e6a0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
e6b0: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
e6c0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
e6d0: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
e6e0: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
e6f0: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
e700: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
e710: 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
e720: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
e730: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
e740: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
e750: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
e760: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
e770: 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
e780: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
e790: 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
e7a0: 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
e7b0: 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
e7c0: 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
e7d0: 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
e7e0: 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
e7f0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
e800: 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
e810: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
e820: 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
e830: 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
e840: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e850: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
e860: 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
e870: 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
e880: 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
e890: 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
e8a0: 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
e8b0: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
e8c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
e8d0: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
e8e0: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
e8f0: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
e900: 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
e910: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
e920: 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
e930: 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
e940: 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
e950: 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
e960: 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61   you.** should a
e970: 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
e980: 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
e990: 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
e9a0: 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a  nto a string .**
e9b0: 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
e9c0: 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
e9d0: 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
e9e0: 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
e9f0: 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
ea00: 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
ea10: 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
ea20: 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20   string.  Or if 
ea30: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
ea40: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
ea50: 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
ea60: 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
ea70: 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
ea80: 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
ea90: 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65   single.** quote
eaa0: 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
eab0: 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45  he %Q option. {E
eac0: 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  ND}  So, for exa
ead0: 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
eae0: 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
eaf0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
eb00: 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
eb10: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
eb20: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
eb30: 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
eb40: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
eb50: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
eb60: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
eb70: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
eb80: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
eb90: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
eba0: 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
ebb0: 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
ebc0: 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
ebd0: 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
ebe0: 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
ebf0: 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
ec00: 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
ec10: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
ec20: 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
ec30: 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
ec40: 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
ec50: 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
ec60: 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
ec70: 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
ec80: 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
ec90: 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
eca0: 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
ecb0: 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
ecc0: 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
ecd0: 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
ece0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
ecf0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d  :.**.** {F17403}
ed00: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
ed10: 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
ed20: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
ed30: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
ed40: 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
ed50: 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
ed60: 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
ed70: 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
ed80: 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
ed90: 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
eda0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
edb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
edc0: 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
edd0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
ede0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
edf0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
ee00: 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ils..**.** {F174
ee10: 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
ee20: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
ee30: 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
ee40: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
ee50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
ee60: 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
ee70: 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
ee80: 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
ee90: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
eea0: 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
eeb0: 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
eec0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
eed0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
eee0: 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37  o..**.** {F17407
eef0: 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
ef00: 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
ef10: 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
ef20: 72 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a  rites slots of.*
ef30: 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
ef40: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
ef50: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
ef60: 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
ef70: 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
ef80: 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
ef90: 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
efa0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
efb0: 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
efc0: 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
efd0: 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
efe0: 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
eff0: 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
f000: 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
f010: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
f020: 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c     .*/.char *sql
f030: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
f040: 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
f050: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
f060: 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
f070: 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
f080: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
f090: 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
f0a0: 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
f0b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f0c0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
f0d0: 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46  ion Subsystem {F
f0e0: 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17300}.**.** The
f0f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
f100: 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
f110: 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
f120: 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
f130: 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
f140: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
f150: 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
f160: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
f170: 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
f180: 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
f190: 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
f1a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
f1b0: 2e 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  .  The.** window
f1c0: 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
f1d0: 65 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72 65  e malloc and fre
f1e0: 65 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  e for some opera
f1f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
f200: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f210: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
f220: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f230: 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
f240: 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
f250: 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
f260: 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
f270: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
f280: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f290: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
f2a0: 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
f2b0: 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
f2c0: 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
f2d0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
f2e0: 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
f2f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
f300: 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
f310: 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
f320: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f330: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
f340: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
f350: 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
f360: 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
f370: 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
f380: 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
f390: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f3a0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
f3b0: 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
f3c0: 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
f3d0: 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
f3e0: 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
f3f0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
f400: 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
f410: 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
f420: 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
f430: 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
f440: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
f450: 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
f460: 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
f470: 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
f480: 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
f490: 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
f4a0: 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
f4b0: 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
f4c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
f4d0: 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
f4e0: 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
f4f0: 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
f500: 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
f510: 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
f520: 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
f530: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
f540: 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
f550: 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
f560: 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
f570: 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
f580: 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
f590: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
f5a0: 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
f5b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
f5c0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
f5d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
f5e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f5f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
f600: 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
f610: 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
f620: 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
f630: 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
f640: 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
f650: 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
f660: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
f670: 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
f680: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
f690: 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
f6a0: 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
f6b0: 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
f6c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
f6d0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
f6e0: 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
f6f0: 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
f700: 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
f710: 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
f720: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f730: 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
f740: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
f750: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f760: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
f770: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f780: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
f790: 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
f7a0: 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
f7b0: 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
f7c0: 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
f7d0: 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
f7e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
f7f0: 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
f800: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f810: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f820: 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69  alloc()..** Sqli
f830: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
f840: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
f850: 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
f860: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
f870: 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
f880: 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
f890: 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
f8a0: 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
f8b0: 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
f8c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
f8d0: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
f8e0: 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
f8f0: 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
f900: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
f910: 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
f920: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
f930: 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
f940: 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
f950: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
f960: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
f970: 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
f980: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f990: 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
f9a0: 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
f9b0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
f9c0: 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
f9d0: 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
f9e0: 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
f9f0: 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
fa00: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
fa10: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
fa20: 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
fa30: 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
fa40: 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
fa50: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
fa60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
fa70: 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
fa80: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
fa90: 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f  m uses the mallo
faa0: 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a  c(), realloc().*
fab0: 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  * and free() pro
fac0: 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
fad0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
fae0: 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {F17382} Howeve
faf0: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
fb00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fb10: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
fb20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
fb30: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
fb40: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d  kquote> SQLITE_M
fb50: 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
fb60: 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  N</i> </blockquo
fb70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
fb80: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e  <i>NNN</i> is an
fb90: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53   integer, then S
fba0: 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
fbb0: 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f  tatic.** array o
fbc0: 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e  f at least <i>NN
fbd0: 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
fbe0: 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61 74  ize and use that
fbf0: 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c   array.** for al
fc00: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
fc10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fc20: 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
fc30: 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d   Additional.** m
fc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
fc50: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
fc60: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
fc70: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
fc80: 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
fc90: 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
fca0: 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
fcb0: 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
fcc0: 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
fcd0: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
fce0: 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
fcf0: 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
fd00: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fd10: 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
fd20: 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
fd30: 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
fd40: 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
fd50: 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
fd60: 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
fd70: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
fd80: 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a  an be.** used..*
fd90: 2a 0a 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77 73  *.** The windows
fda0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
fdb0: 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
fdc0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
fdd0: 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
fde0: 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
fdf0: 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
fe00: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
fe10: 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
fe20: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
fe30: 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
fe40: 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
fe50: 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
fe60: 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a  ticular windows.
fe70: 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
fe80: 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
fe90: 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
fea0: 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
feb0: 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
fec0: 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
fed0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
fee0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
fef0: 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
ff00: 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
ff10: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
ff20: 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54  *.** {F17303}  T
ff30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
ff40: 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
ff50: 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
ff60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a  a pointer to .**
ff70: 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79             newly
ff80: 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
ff90: 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
ffa0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ffb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
ffc0: 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
ffd0: 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20  gned, .**       
ffe0: 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e      or it return
fff0: 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
10000 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c  unable to fulfil
10010 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a  l the request..*
10020 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54  *.** {F17304}  T
10030 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
10040 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
10050 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
10060 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20  pointer if.**   
10070 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73          N is les
10080 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
10090 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  to zero..**.** {
100a0 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71  F17305}  The [sq
100b0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69  lite3_free(P)] i
100c0 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65  nterface release
100d0 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75  s memory previou
100e0 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
100f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
10100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10110 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
10120 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
10130 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74         making it
10140 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72   available for r
10150 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  euse..**.** {F17
10160 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  306}  A call to 
10170 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55  [sqlite3_free(NU
10180 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65  LL)] is a harmle
10190 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
101a0 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c  {F17310}  A call
101b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
101c0 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71  lloc(0,N)] is eq
101d0 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
101e0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
101f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
10200 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  oc(N)]..**.** {F
10210 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74  17312}  A call t
10220 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
10230 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69  oc(P,0)] is equi
10240 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
10250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
10260 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
10270 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
10280 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  5}  The SQLite c
10290 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65  ore uses [sqlite
102a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
102b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
102c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  ,.**           a
102d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  nd [sqlite3_free
102e0 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ()] for all of i
102f0 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ts memory alloca
10300 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
10310 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69        deallocati
10320 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
10330 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73  {F17318}  The [s
10340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
10350 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
10360 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
10370 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
10380 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20       to a block 
10390 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
103a0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
103b0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
103c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
103d0 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
103e0 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c  igned, or a NULL
103f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
10400 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b  {F17321}  When [
10410 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10420 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
10430 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
10440 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
10450 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74          copies t
10460 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73  he first K bytes
10470 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d   of content from
10480 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c   P into the newl
10490 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20  y allocated.**  
104a0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4b           where K
104b0 20 69 73 20 74 68 65 20 6c 65 73 73 6f 72 20 6f   is the lessor o
104c0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
104d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 50   of the buffer P
104e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d  ..**.** {F17322}
104f0 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
10500 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
10510 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
10520 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
10530 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
10540 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66  releases the buf
10550 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fer P..**.** {F1
10560 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7323}  When [sql
10570 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
10580 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  )] returns NULL,
10590 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73   the buffer P is
105a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
105b0 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65  t modified or re
105c0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49  leased..**.** LI
105d0 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
105e0 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70   {U17350}  The p
105f0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
10600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
10610 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
10620 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
10630 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62            must b
10640 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
10650 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20   else a pointer 
10660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
10670 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
10680 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
10690 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
106a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
106b0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
106c0 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  has.**          
106d0 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73   not been releas
106e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35  ed..**.** {U1735
106f0 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
10700 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
10710 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
10720 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20  art of .**      
10730 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
10740 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
10750 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
10760 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
10770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
10780 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
10790 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  3_realloc()]..**
107a0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
107b0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
107c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
107d0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
107e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
107f0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
10800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
10810 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
10820 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37 30  atistics {F17370
10830 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  }.**.** SQLite p
10840 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
10850 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
10860 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
10870 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
10880 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
10890 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
108a0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
108b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
108c0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
108d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
108e0 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
108f0 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a  hin the SQLite..
10900 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10910 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d  :.**.** {F17371}
10920 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10930 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
10940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
10950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
10960 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
10970 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
10980 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a   outstanding .**
10990 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f            (mallo
109a0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
109b0 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  d)..**.** {F1737
109c0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
109d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
109e0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
109f0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
10a00 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
10a10 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
10a20 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a  mory_used()] .**
10a30 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 65 20            since 
10a40 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
10a50 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  rk was last rese
10a60 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34  t..**.** {F17374
10a70 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
10a80 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
10a90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
10aa0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
10ab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10ac0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
10ad0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
10ae0 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
10af0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
10b00 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
10b10 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
10b20 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
10b30 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
10b40 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
10b50 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
10b60 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
10b70 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
10b80 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
10b90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10ba0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a   may call..** .*
10bb0 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d  * {F17375} The m
10bc0 65 6d 6f 72 79 20 68 69 67 68 77 61 74 65 72 20  emory highwater 
10bd0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
10be0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
10bf0 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ue of.**        
10c00 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
10c10 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
10c20 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
10c30 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
10c40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
10c50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10c60 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65  )] is true.  The
10c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
10c80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
10c90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10ca0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
10cb0 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
10cc0 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rk.**          p
10cd0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
10ce0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
10cf0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
10d00 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
10d10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
10d20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10d30 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
10d40 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
10d50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
10d60 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
10d70 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
10d80 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500}.**.** This 
10d90 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
10da0 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
10db0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
10dc0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 64 61 74  articular.** dat
10dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10de0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
10df0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10e00 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
10e10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
10e20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
10e30 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
10e40 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
10e50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
10e60 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
10e70 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
10e80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
10e90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
10ea0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
10eb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
10ec0 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75  2()].  At variou
10ed0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
10ee0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
10ef0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
10f00 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
10f10 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
10f20 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
10f30 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
10f40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
10f50 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
10f60 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
10f70 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
10f80 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
10f90 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
10fa0 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ** return SQLITE
10fb0 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  _OK to allow the
10fc0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
10fd0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
10fe0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
10ff0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
11000 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
11010 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
11020 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
11030 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
11040 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
11050 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
11060 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
11070 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
11080 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20   an error.   If 
11090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
110a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
110b0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
110c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
110d0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
110e0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
110f0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b  _DENY].** then [
11100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11110 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
11120 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
11130 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
11140 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
11150 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
11160 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
11170 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
11180 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
11190 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
111a0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
111b0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
111c0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
111d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
111e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
111f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
11200 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11210 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11220 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
11230 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
11240 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
11250 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
11260 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
11270 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
11280 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
11290 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
112a0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
112b0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
112c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
112d0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
112e0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
112f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
11300 73 74 72 75 63 74 65 64 20 74 6f 20 69 6e 73 65  structed to inse
11310 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
11320 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
11330 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
11340 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
11350 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
11360 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
11370 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
11380 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
11390 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
113a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
113b0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
113c0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
113d0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
113e0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
113f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
11400 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11410 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11420 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
11430 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  f.** the third p
11440 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
11450 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
11460 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
11470 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ce..** The secon
11480 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11490 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
114a0 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53  n integer .** [S
114b0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
114c0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
114d0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
114e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
114f0 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  * to be authoriz
11500 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
11510 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70  rough sixth.** p
11520 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
11530 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
11540 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
11550 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
11560 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  in .** additiona
11570 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
11580 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
11590 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
115a0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
115b0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72   is used when pr
115c0 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74  eparing SQL stat
115d0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
115e0 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72  ntrusted.** sour
115f0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
11600 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
11610 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79  ments do not try
11620 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a   to access data.
11630 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65  ** that they are
11640 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
11650 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
11660 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a  y do not try to.
11670 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  ** execute malic
11680 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
11690 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
116a0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
116b0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
116c0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
116d0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
116e0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
116f0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
11700 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
11710 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
11720 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
11730 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
11740 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
11750 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
11760 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
11770 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
11780 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
11790 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
117a0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
117b0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
117c0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
117d0 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61  ing prepared tha
117e0 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  t disallows ever
117f0 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74  ything.** except
11800 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
11810 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  ts.  .**.** Only
11820 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
11830 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
11840 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
11850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
11860 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
11870 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
11880 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
11890 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
118a0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
118b0 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
118c0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
118d0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
118e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
118f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
11900 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11910 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
11920 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
11930 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
11940 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
11950 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
11960 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
11970 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
11980 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
11990 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
119a0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
119b0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
119c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
119d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
119e0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54  **.** {F12501} T
119f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
11a00 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e  authorizer(D,...
11a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
11a20 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20  isters a.**     
11a30 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
11a40 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61  callback with da
11a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11a60 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  n D..**.** {F125
11a70 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a  02} The authoriz
11a80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
11a90 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
11aa0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
11ab0 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63           being c
11ac0 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46  ompiled.**.** {F
11ad0 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
11ae0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
11af0 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
11b00 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
11b10 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
11b20 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
11b30 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
11b40 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a  ITE_DENY] then.*
11b50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
11b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11b70 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
11b80 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
11b90 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
11ba0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11bb0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
11bc0 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
11bd0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
11be0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
11bf0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
11c00 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
11c10 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
11c20 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {F12504} When t
11c30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11c40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
11c50 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
11c60 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
11c70 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
11c80 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c  is coded normall
11c90 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35  y..**.** {F12505
11ca0 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
11cb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
11cc0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
11cd0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20  ENY], the.**    
11ce0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
11cf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11d00 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11d10 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
11d20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
11d30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11d40 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
11d50 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
11d60 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
11d70 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
11d80 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
11d90 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
11da0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
11db0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
11dc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36  d..**.** {F12506
11dd0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
11de0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
11df0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11e00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
11e10 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
11e20 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
11e30 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
11e40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11e50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
11e60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
11e70 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72  ORE] then the pr
11e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11e90 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
11ea0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
11eb0 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c  nsert a NULL val
11ec0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
11ed0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
11ee0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
11ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e  **          been
11f00 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
11f10 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
11f20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  turned..**.** {F
11f30 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75  12507} If the au
11f40 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
11f50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
11f60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
11f70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
11f80 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74  allback) is anyt
11f90 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
11fa0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74  [SQLITE_READ], t
11fb0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
11fc0 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c  a return of [SQL
11fd0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20  ITE_IGNORE] has 
11fe0 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20  the same effect 
11ff0 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  as [SQLITE_DENY]
12000 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30  . .**.** {F12510
12010 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
12020 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
12030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12040 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
12050 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
12060 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
12070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
12080 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
12090 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
120a0 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65   {F12511} The se
120b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
120c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
120d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a  s an integer .**
120e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
120f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
12100 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
12110 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
12120 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
12130 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
12140 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
12150 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  F12512} The thir
12160 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
12170 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12180 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
12190 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
121a0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
121b0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
121c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
121d0 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
121e0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
121f0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
12200 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30  d..**.** {F12520
12210 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
12220 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12230 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69  orizer()] overri
12240 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  des the.**      
12250 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73      any previous
12260 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74  ly installed aut
12270 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  horizer..**.** {
12280 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61  F12521} A NULL a
12290 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
122a0 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
122b0 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
122c0 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e    callback is in
122d0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
122e0 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
122f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
12300 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
12310 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12320 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
12330 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
12340 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
12350 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
12360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
12370 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
12380 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
12390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
123a0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
123b0 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39  urn Codes {F1259
123c0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
123d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
123e0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
123f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
12400 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
12410 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
12420 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
12430 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
12440 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
12450 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
12460 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
12470 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
12480 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
12490 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
124a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
124b0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
124c0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
124d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
124e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
124f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
12500 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
12510 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
12520 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
12530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12540 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
12550 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
12560 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
12570 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
12580 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
12590 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
125a0 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35  tion Codes {F125
125b0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  50}.**.** The [s
125c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
125d0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
125e0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
125f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12600 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
12610 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
12620 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  r certain SQL st
12630 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
12640 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
12650 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12660 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
12670 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
12680 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
12690 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
126a0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
126b0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
126c0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
126d0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
126e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
126f0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
12700 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
12710 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
12720 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
12730 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
12740 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75   is to be .** au
12750 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
12760 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
12770 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
12780 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
12790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
127a0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
127b0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
127c0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
127d0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
127e0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
127f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
12800 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
12810 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
12820 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12830 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
12840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
12850 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a  main", "temp", .
12860 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
12870 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
12880 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12890 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
128a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
128b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
128c0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
128d0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
128e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
128f0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
12900 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
12910 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
12920 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
12930 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76  from .** top-lev
12940 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a  el SQL code..**.
12950 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
12960 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54 68  *.** {F12551} Th
12970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12980 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20  er to an .**    
12990 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
129a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
129b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
129c0 61 63 6b 20 69 73 20 61 6c 77 61 79 73 20 61 6e  ack is always an
129d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
129e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
129f0 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
12a00 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
12a10 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a  ies what action.
12a20 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62  **          is b
12a30 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
12a40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20  .**.** {F12552} 
12a50 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
12a60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
12a70 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
12a80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12a90 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
12aa0 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  zation callback 
12ab0 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  function].**    
12ac0 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61        will be pa
12ad0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
12ae0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
12af0 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ich .**         
12b00 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
12b10 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
12b20 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
12b30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12b40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d  ..**.** {F12553}
12b50 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
12b60 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
12b70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
12b80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
12b90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
12ba0 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
12bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
12bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78  the database (ex
12bd0 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22  ample: "main", "
12be0 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20  temp", etc.) if 
12bf0 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a  applicable..**.*
12c00 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36  * {F12554} The 6
12c10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
12c20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12c30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12c40 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12c50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
12c60 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
12c70 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
12c80 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
12c90 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
12ca0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
12cc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
12cd0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
12ce0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
12cf0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
12d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70  .**          top
12d10 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
12d20 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
12d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d50 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
12d60 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
12d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12d80 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
12d90 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
12da0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
12db0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
12dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12dd0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
12de0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
12df0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
12e00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
12e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12e20 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
12e30 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
12e40 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
12e50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
12e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e70 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
12e80 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
12e90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
12ea0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
12eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12ec0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
12ed0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
12ee0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
12ef0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
12f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12f10 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
12f20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
12f30 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
12f40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
12f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
12f60 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
12f70 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
12f80 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
12f90 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
12fa0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
12fb0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
12fc0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
12fd0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
12fe0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
12ff0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
13000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
13010 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
13020 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
13030 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13040 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
13050 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
13060 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
13070 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
13080 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13090 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
130a0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
130b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
130c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
130d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
130e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
130f0 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
13100 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
13110 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
13120 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13130 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
13140 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
13150 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13160 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13180 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
13190 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
131a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
131b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
131c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
131d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
131e0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
131f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
13200 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13220 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
13230 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
13240 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
13250 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13270 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
13280 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
13290 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
132a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
132b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
132c0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
132d0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
132e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
132f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13310 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
13320 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
13330 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
13340 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
13350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
13360 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
13370 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
13380 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
13390 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
133a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
133b0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
133c0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
133d0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
133e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
133f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
13400 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
13410 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    22   /* NULL  
13420 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
13430 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13440 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
13450 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
13460 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
13470 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
13480 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
13490 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
134a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
134b0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
134c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
134d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
134e0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
134f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
13500 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
13510 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
13520 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13530 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
13540 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
13550 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
13560 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
13570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13580 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
13590 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
135a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
135b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
135c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
135d0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
135e0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
135f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13600 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
13630 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
13640 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13650 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
13660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13670 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
13680 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
13690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
136a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
136b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
136c0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
136d0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
136e0 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
136f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13710 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
13720 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
13730 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
13740 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
13750 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
13760 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
13770 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a  ns {F12280}.**.*
13780 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
13790 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
137a0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
137b0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
137c0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
137d0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
137e0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
137f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
13800 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
13810 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
13820 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
13830 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
13840 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
13850 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
13860 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
13870 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
13880 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
13890 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  The callback ret
138a0 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e  urns a UTF-8 ren
138b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51  dering of the SQ
138c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
138d0 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65  .** as the state
138e0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
138f0 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64  s executing.  Ad
13900 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  ditional callbac
13910 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ks occur.** as e
13920 61 63 68 20 74 72 69 67 67 65 72 73 75 62 70 72  ach triggersubpr
13930 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
13940 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
13950 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
13960 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
13970 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
13980 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
13990 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a   trigger..** .**
139a0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
139b0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
139c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
139d0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
139e0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
139f0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
13a00 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c  hes.  The profil
13a10 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
13a20 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
13a30 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
13a40 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
13a50 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
13a60 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
13a70 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
13a80 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
13a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13aa0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49  e3_profile() API
13ab0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
13ac0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
13ad0 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20  ental and.** is 
13ae0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
13af0 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20  e or removal in 
13b00 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
13b10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67  ..**.** The trig
13b20 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65  ger reporting fe
13b30 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72 61  ature of the tra
13b40 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ce callback is c
13b50 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70  onsidered.** exp
13b60 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
13b70 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
13b80 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
13b90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
13ba0 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73  ..** Future vers
13bb0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
13bc0 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65  ight also add ne
13bd0 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  w trace callback
13be0 20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73   .** invocations
13bf0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
13c00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  TS:.**.** {F1228
13c10 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
13c20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
13c30 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
13c40 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20  trace()] is.**  
13c50 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
13c60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
13c70 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
13c80 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
13c90 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
13ca0 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
13cb0 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
13cc0 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
13cd0 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68  ** {F12282} Each
13ce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
13cf0 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72  3_trace()] overr
13d00 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
13d10 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
13d20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65  registered trace
13d30 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
13d40 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c   {F12283} A NULL
13d50 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
13d60 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67  disables tracing
13d70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d  ..**.** {F12284}
13d80 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13d90 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
13da0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
13db0 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
13dc0 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
13dd0 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
13de0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
13df0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
13e00 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54  **.** {F12285} T
13e10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13e20 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
13e30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
13e40 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
13e50 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73  erminated UTF8 s
13e60 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
13e70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
13e80 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
13e90 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
13ea0 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
13eb0 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
13ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
13ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
13ee0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
13ef0 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
13f00 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
13f10 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
13f20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
13f30 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
13f40 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54  **.** {F12287} T
13f50 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
13f60 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
13f70 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
13f80 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
13f90 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
13fa0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
13fb0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
13fc0 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65  .** {F12288} The
13fd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13fe0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
13ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
14000 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
14010 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
14020 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
14030 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
14040 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73  * {F12289} The s
14050 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14060 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
14070 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
14080 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
14090 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
140a0 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
140b0 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
140c0 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
140d0 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
140e0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
140f0 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
14100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14110 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
14120 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
14130 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39  nt..**.** {F1229
14140 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
14150 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
14160 6f 66 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20  ofile  callback 
14170 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
14180 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
14190 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
141a0 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
141b0 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
141c0 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
141d0 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
141e0 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
141f0 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
14200 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
14210 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
14220 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
14230 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
14240 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
14250 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
14260 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
14270 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
14280 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
14290 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
142a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
142b0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
142c0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
142d0 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12910}.**.**
142e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
142f0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
14300 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
14310 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
14320 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
14330 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
14340 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
14350 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
14360 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
14370 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
14380 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
14390 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
143a0 62 6c 65 28 29 5d 2e 20 20 20 41 6e 20 65 78 61  ble()].   An exa
143b0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
143c0 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  s .** interface 
143d0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
143e0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
143f0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
14400 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67  *.** If the prog
14410 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
14420 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
14430 74 68 65 20 6f 70 65 72 74 69 6f 6e 20 69 73 0a  the opertion is.
14440 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
14450 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
14460 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
14470 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
14480 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
14490 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e   GUI dialog box.
144a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
144b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31  S:.**.** {F12911
144c0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
144d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
144e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
144f0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
14500 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
14510 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
14520 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
14530 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
14540 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
14550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14560 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d  ..**.** {F12912}
14570 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
14580 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14590 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
145a0 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20   N virtual.**   
145b0 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f         machine o
145c0 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20  pcodes, where N 
145d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
145e0 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20  gument to .**   
145f0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
14600 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14610 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
14620 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
14630 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
14640 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68  lback.  <todo>Wh
14650 61 74 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  at if N is less 
14660 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a  than 1?</todo>.*
14670 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68  *.** {F12913} Th
14680 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14690 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
146a0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
146b0 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
146c0 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73    argument to [s
146d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
146e0 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a  handler()]..**.*
146f0 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66  * {F12914} The f
14700 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 5b  ourth argument [
14710 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
14720 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 20 61  _handler()] is a
14730 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f 69  .***         voi
14740 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
14750 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
14760 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
14770 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
14780 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
14790 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
147a0 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
147b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
147c0 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
147d0 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  fewer than.**   
147e0 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65 73         N opcodes
147f0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
14800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14810 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  n the progress c
14820 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72  allback is never
14830 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a   invoked. {END}.
14840 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20  ** .** {F12916} 
14850 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73  Every call to [s
14860 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
14870 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
14880 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65         overwrite
14890 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  s any previously
148a0 20 72 65 67 69 73 74 65 72 65 20 70 72 6f 67 72   registere progr
148b0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  ess handler..**.
148c0 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20 74  ** {F12917} If t
148d0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
148e0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
148f0 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f  NULL then no pro
14900 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20  gress.**        
14910 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76    handler is inv
14920 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
14930 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67  918} If the prog
14940 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
14950 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f  turns a result o
14960 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65  ther than 0, the
14970 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
14980 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20  e behavior is a 
14990 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  if [sqlite3_inte
149a0 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65  rrupt()] had bee
149b0 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69  n called..*/.voi
149c0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
149d0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
149e0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
149f0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
14a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14a10 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
14a20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
14a30 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a  ion {F12700}.**.
14a40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
14a50 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
14a60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
14a70 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20  hose name.** is 
14a80 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69 6c  given by the fil
14a90 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ename argument..
14aa0 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  ** The filename 
14ab0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
14ac0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
14ad0 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  .** for [sqlite3
14ae0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
14af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
14b00 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
14b10 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
14b20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
14b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
14b40 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  ]..** An [sqlite
14b50 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  3*] handle is us
14b60 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 20 69  ually returned i
14b70 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a  n *ppDb, even.**
14b80 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
14b90 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
14ba0 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 20 53  xception is if S
14bb0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 0a  QLite is unable.
14bc0 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ** to allocate m
14bd0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
14be0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
14bf0 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a  ct, a NULL will.
14c00 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ** be written in
14c10 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
14c20 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
14c30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
14c40 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65  bject..** If the
14c50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
14c60 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
14c70 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 73 66  ted).** successf
14c80 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49  ully, then [SQLI
14c90 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
14ca0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
14cb0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
14cc0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
14cd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
14ce0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
14cf0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
14d00 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
14d10 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
14d20 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
14d30 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
14d40 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
14d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
14d60 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
14d70 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
14d80 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
14d90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14da0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
14db0 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
14dc0 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
14dd0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
14de0 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71  yte order if [sq
14df0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
14e00 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
14e10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
14e20 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
14e30 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
14e40 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
14e50 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
14e60 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  e [sqlite3*] han
14e70 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
14e80 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e  leased by passin
14e90 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  g it.** to [sqli
14ea0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
14eb0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
14ec0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
14ed0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  * The [sqlite3_o
14ee0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
14ef0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b  ace works like [
14f00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
14f10 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
14f20 69 74 20 61 63 63 63 65 70 74 73 20 74 77 6f 20  it acccepts two 
14f30 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
14f40 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
14f50 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
14f60 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
14f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14f80 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
14f90 61 6d 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a  ameter can be.**
14fa0 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c   one of:.**.** <
14fb0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ol>.** <li>  [SQ
14fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
14fd0 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  LY].** <li>  [SQ
14fe0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
14ff0 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  ITE].** <li>  [S
15000 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
15010 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
15020 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20  OPEN_CREATE].** 
15030 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ol>.**.** The 
15040 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e  first value open
15050 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72  s the database r
15060 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66  ead-only. .** If
15070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
15080 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  es not previousl
15090 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
150a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
150b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74  * The second opt
150c0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65  ion opens.** the
150d0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
150e0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
150f0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
15100 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
15110 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  f.** if the file
15120 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
15130 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20  ted.  In either 
15140 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
15150 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64  e.** must alread
15160 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72  y exist or an er
15170 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
15180 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69    The third opti
15190 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20  on.** opens the 
151a0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
151b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
151c0 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20   and creates it 
151d0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
151e0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
151f0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70  .** The third op
15200 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f  tions is behavio
15210 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
15220 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74   used for [sqlit
15230 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  e3_open()].** an
15240 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
15250 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  6()]..**.** If t
15260 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
15270 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
15280 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e  an private.** in
15290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
152a0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
152b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
152c0 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a   This in-memory.
152d0 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ** database will
152e0 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65   vanish when the
152f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15300 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
15310 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
15320 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  on of SQLite mig
15330 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ht make use of a
15340 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
15350 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74  l filenames.** t
15360 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
15370 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
15380 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  .  It is recomme
15390 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68  nded that .** wh
153a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
153b0 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f  lename really do
153c0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
153d0 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72   ":" that you pr
153e0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
153f0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
15400 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a  e like "./" to.*
15410 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  * avoid ambiguit
15420 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
15430 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
15440 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
15450 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 6d 70  n a private temp
15460 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
15470 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
15480 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
15490 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
154a0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
154b0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
154c0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
154d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
154e0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
154f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
15500 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
15510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15520 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
15530 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15540 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
15550 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
15560 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a  rating system .*
15570 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  * interface that
15580 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
15590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
155a0 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65  uld use.  If the
155b0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
155c0 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70  eter is a NULL p
155d0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
155e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
155f0 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  _vfs].** object 
15600 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
15610 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77  b>Note to window
15620 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
15630 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
15640 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
15650 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15670 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
15680 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65  en_v2()] must be
15690 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
156a0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
156b0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
156c0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
156d0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
156e0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
156f0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
15700 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
15710 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
15720 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
15730 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
15740 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
15750 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
15760 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15770 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
15780 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15790 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
157a0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
157b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
157c0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
157d0 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
157e0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
157f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15800 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
15810 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
15820 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
15830 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
15840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15850 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
15860 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
15870 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
15880 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
15890 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
158a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
158b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
158c0 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
158d0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
158e0 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
158f0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
15900 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15910 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
15920 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
15930 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
15940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
15950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15960 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ], .**          
15970 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15980 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20  _v2()] writes a 
15990 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
159a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
159b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
159c0 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a  n] into *ppDb..*
159d0 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68  *.** {F12704} Th
159e0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
159f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15a00 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
15a10 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
15a20 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
15a30 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53  rfaces return [S
15a40 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73  QLITE_OK] upon s
15a50 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20  uccess,.**      
15a60 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70      or an approp
15a70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
15a80 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
15a90 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68  *.** {F12706} Th
15aa0 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
15ab0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
15ac0 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
15ad0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
15ae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
15af0 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
15b00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c  3_open_v2()] wil
15b10 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  l be UTF-8..**.*
15b20 2a 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64  * {F12707} The d
15b30 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
15b40 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
15b50 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
15b60 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
15b70 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31    [sqlite3_open1
15b80 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  6()] will be UTF
15b90 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  -16..**.** {F127
15ba0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
15bb0 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65  _open(F,D)] inte
15bc0 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
15bd0 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
15be0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15bf0 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68  _v2(F,D,G,0)] wh
15c00 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65  ere the G parame
15c10 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
15c20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f     [SQLITE_OPEN_
15c30 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49  READWRITE]|[SQLI
15c40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
15c50 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20  .**.** {F12711} 
15c60 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
15c70 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
15c80 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
15c90 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
15ca0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
15cb0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
15cc0 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20  _READONLY] then 
15cd0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
15ce0 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
15cf0 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f     for reading o
15d00 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  nly..**.** {F127
15d10 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  12} If the G par
15d20 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15d30 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
15d40 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
15d50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
15d60 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
15d70 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
15d80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
15d90 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
15da0 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20          reading 
15db0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
15dc0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20  ossible, or for 
15dd0 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20  reading only if 
15de0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15df0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
15e00 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
15e10 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
15e20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20  .**.** {F12713} 
15e30 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
15e40 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
15e50 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen(v2(F,D,G,V)]
15e60 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20   omits the.**   
15e70 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
15e80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
15e90 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
15ea0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
15eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
15ec0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
15ed0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
15ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ed..**.** {F1271
15ef0 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  4} If the G para
15f00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
15f10 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c  3_open(v2(F,D,G,
15f20 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
15f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
15f40 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
15f50 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
15f60 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
15f70 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
15f80 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
15f90 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65  st, then an atte
15fa0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63  mpt is made to c
15fb0 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20  reate and.**    
15fc0 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65        initialize
15fd0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a   the database..*
15fe0 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66  *.** {F12717} If
15ff0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
16000 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
16010 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
16020 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
16030 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
16040 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16050 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  )] is ":memory:"
16060 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74  , then an privat
16070 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
16080 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d  phemeral, in-mem
16090 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
160a0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
160b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20  connection..**  
160c0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73          <todo>Is
160d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
160e0 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ATE|SQLITE_OPEN_
160f0 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72  READWRITE requir
16100 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
16110 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  n sqlite3_open_v
16120 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  2()?</todo>.**.*
16130 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68  * {F12719} If th
16140 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
16150 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
16160 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 65  hen a private, e
16170 70 68 65 72 6d 65 72 61 6c 0a 2a 2a 20 20 20 20  phermeral.**    
16180 20 20 20 20 20 20 6f 6e 2d 64 69 73 6b 20 64 61        on-disk da
16190 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
161a0 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
161b0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
161c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
161d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
161e0 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
161f0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
16200 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
16210 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
16220 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
16230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16240 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20   created by .** 
16250 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
16260 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
16270 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65  V)] will use the
16280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16290 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
162a0 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
162b0 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
162c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
162d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
162e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
162f0 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   is V is a NULL 
16300 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  pointer..*/.int 
16310 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
16320 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
16330 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
16340 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
16350 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
16360 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
16370 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
16380 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
16390 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
163a0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
163b0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
163c0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
163d0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
163e0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
163f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
16400 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
16410 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
16420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
16430 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
16440 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
16450 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
16460 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
16470 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
16480 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
16490 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
164a0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
164b0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
164c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
164d0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
164e0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
164f0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
16500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16510 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
16520 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38  d Messages {F128
16530 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
16540 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
16550 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16560 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
16570 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
16580 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53  sult code] or [S
16590 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
165a0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
165b0 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20  lt code].** for 
165c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
165d0 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
165e0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
165f0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71  ated.** with [sq
16600 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64  lite3] handle 'd
16610 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  b'. If a prior A
16620 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62  PI call failed b
16630 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  ut the.** most r
16640 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
16650 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
16660 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
16670 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16680 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
16690 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
166a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
166b0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
166c0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
166d0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
166e0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
166f0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
16700 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72  s either UTF8 or
16710 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76   UTF16 respectiv
16720 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
16730 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
16740 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
16750 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
16760 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
16770 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
16780 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
16790 20 77 69 74 68 20 66 72 65 65 69 6e 67 20 74 68   with freeing th
167a0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
167b0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
167c0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
167d0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
167e0 65 61 6c 6c 6f 63 61 74 65 64 20 62 0a 2a 2a 20  eallocated b.** 
167f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
16800 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
16810 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
16820 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
16830 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
16840 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12801} The [sqli
16850 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20  te3_errcode(D)] 
16860 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16870 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
16880 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16890 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
168a0 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  de] or.**       
168b0 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52     [SQLITE_IOERR
168c0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
168d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
168e0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
168f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
16900 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
16910 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
16920 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
16930 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65  [sqlite3] handle
16940 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 38 30   D..**.** {U1280
16950 32 7d 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  2} If a prior AP
16960 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75  I call failed bu
16970 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
16980 74 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 20 20  t API call.**   
16990 20 20 20 20 20 20 20 73 75 63 63 65 65 64 65 64         succeeded
169a0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
169b0 75 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ue from [sqlite3
169c0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
169d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
169e0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
169f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16a00 31 36 28 29 5d 20 61 72 65 20 75 6e 64 65 66 69  16()] are undefi
16a10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ned..**.** {F128
16a20 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
16a30 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
16a40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
16a50 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
16a60 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
16a70 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
16a80 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
16a90 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
16aa0 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
16ab0 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
16ac0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
16ad0 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
16ae0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
16af0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
16b00 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
16b10 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  ively..**.** {U1
16b20 32 38 30 34 7d 20 54 68 65 20 73 74 72 69 6e 67  2804} The string
16b30 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16b40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16b50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
16b60 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
16b70 20 20 20 20 20 20 61 72 65 20 6f 6e 6c 79 20 76        are only v
16b80 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
16b90 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ext SQLite inter
16ba0 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  face call..**.**
16bb0 20 7b 46 31 32 38 30 37 7d 20 43 61 6c 6c 73 20   {F12807} Calls 
16bc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
16bd0 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
16be0 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 0a  _errmsg()], and.
16bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16c00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
16c10 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
16c20 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a 2a  ot affect the.**
16c30 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
16c40 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f  s of future invo
16c50 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  cations of these
16c60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
16c70 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20   {F12808} Calls 
16c80 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  to API routines 
16c90 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75  that do not retu
16ca0 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  rn an error code
16cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78  .**          (ex
16cc0 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f  ample: [sqlite3_
16cd0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64  data_count()]) d
16ce0 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  o not.**        
16cf0 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72    change the err
16d00 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61  or code or messa
16d10 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ge returned by.*
16d20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16d30 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
16d40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
16d50 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
16d60 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
16d70 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65  ** {F12809} Inte
16d80 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20  rfaces that are 
16d90 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
16da0 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a  ith a specific.*
16db0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
16dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16dd0 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20   (examples:.**  
16de0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
16df0 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b  _mprintf()] or [
16e00 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
16e10 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a  hared_cache()].*
16e20 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f  *          do no
16e30 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
16e40 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
16e50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16e60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
16e70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16e80 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
16e90 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
16ea0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
16eb0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
16ec0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
16ed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
16ee0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
16ef0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
16f00 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
16f10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f20 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
16f30 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a  Object {F13000}.
16f40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
16f50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
16f60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
16f70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
16f80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
16f90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
16fa0 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74  nt single SQL st
16fb0 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a  atements.  This.
16fc0 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  ** object is var
16fd0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
16fe0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
16ff0 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20  ement" or a .** 
17000 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
17010 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
17020 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
17030 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  nt"..** .** The 
17040 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
17050 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
17060 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
17070 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
17080 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
17090 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
170a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
170b0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
170c0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
170d0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
170e0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
170f0 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69  t parameters usi
17100 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
17110 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
17120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69  sqlite3_bind_* i
17130 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c  nterfaces]..** <
17140 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
17150 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
17160 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
17170 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
17180 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
17190 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
171a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
171b0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
171c0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
171d0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
171e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
171f0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
17200 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
17210 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
17220 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
17230 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
17240 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
17250 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
17260 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
17270 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
17280 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
17290 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
172a0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
172b0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
172c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
172d0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
172e0 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13010}.**.** 
172f0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
17300 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
17310 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
17320 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
17330 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
17340 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
17350 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
17360 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17370 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
17380 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17390 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69  ction] .** obtai
173a0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
173b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
173c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
173d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a  te3_open_v2()].*
173e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
173f0 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65  en16()]. .** The
17400 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17410 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73   "zSql" is the s
17420 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
17430 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
17440 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
17450 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
17460 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
17470 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
17480 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
17490 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
174a0 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69  s UTF-8 and sqli
174b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
174c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
174d0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
174e0 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a  e UTF-16. {END}.
174f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
17500 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
17510 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f  ess.** than zero
17520 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
17530 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
17540 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
17550 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65  tor..** If nByte
17560 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
17570 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
17580 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
17590 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61  of .** bytes rea
175a0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
175b0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
175c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
175d0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
175e0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
175f0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
17600 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
17610 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20  er or .** until 
17620 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
17630 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
17640 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 7d 0a  es first. {END}.
17650 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73  **.** *pzTail is
17660 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
17670 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
17680 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
17690 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51   the.** first SQ
176a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
176b0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
176c0 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  ines only compil
176d0 65 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  es the first.** 
176e0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
176f0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
17700 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
17710 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a  o what remains.*
17720 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  * uncompiled..**
17730 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
17740 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
17750 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
17760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
17770 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
17780 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
17790 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
177a0 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 73 20   Or if there is 
177b0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
177c0 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 20  t may be.** set 
177d0 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
177e0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
177f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
17800 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20  the input.** is 
17810 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67  and empty string
17820 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
17830 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
17840 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b  et to NULL..** {
17850 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c  U13018} The call
17860 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
17870 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
17880 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a   deleting the.**
17890 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
178a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67  atement.** using
178b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
178c0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
178d0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
178e0 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
178f0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
17900 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
17910 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a   Otherwise an .*
17920 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
17930 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17940 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
17950 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
17960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17970 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
17980 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
17990 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
179a0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
179b0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
179c0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
179d0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
179e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
179f0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
17a00 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
17a10 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
17a20 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
17a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
17a40 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
17a50 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
17a60 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
17a70 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
17a80 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69  of the .** origi
17a90 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45  nal SQL text. {E
17aa0 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73 20  ND} This causes 
17ab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
17ac0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
17ad0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
17ae0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
17af0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
17b00 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
17b10 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
17b20 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
17b30 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
17b40 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
17b50 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
17b60 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
17b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
17b80 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
17b90 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
17ba0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
17bb0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
17bc0 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
17bd0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
17be0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
17bf0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
17c00 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
17c10 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
17c20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
17c30 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
17c40 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
17c50 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
17c60 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
17c70 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  r, .** [SQLITE_S
17c80 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20  CHEMA] is now a 
17c90 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
17ca0 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  lling.** [sqlite
17cb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17cc0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
17cd0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
17ce0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
17cf0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
17d00 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
17d10 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
17d20 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
17d30 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
17d40 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
17d50 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44  MA] return. {END
17d60 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  }.** </li>.**.**
17d70 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
17d80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a   error occurs, .
17d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
17da0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
17db0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
17dc0 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  led .** [error c
17dd0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
17de0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
17df0 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20   .** The legacy 
17e00 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
17e10 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  t [sqlite3_step(
17e20 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
17e30 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a  turn a generic.*
17e40 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
17e50 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64   result code and
17e60 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
17e70 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
17e80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
17e90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
17ea0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
17eb0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
17ec0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
17ed0 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  em..** With the 
17ee0 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74  "v2" prepare int
17ef0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
17f00 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
17f10 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a  or the error is.
17f20 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  ** returned imme
17f30 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
17f40 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
17f50 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
17f60 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20  ** {F13011} The 
17f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17f80 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
17f90 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
17fa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17fb0 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
17fc0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
17fd0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
17fe0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
17ff0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
18000 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
18010 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20  ** {F13012} The 
18020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18030 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
18040 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18050 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18060 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
18070 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
18080 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
18090 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
180a0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
180b0 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
180c0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
180d0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
180e0 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68 65   {F13013} If the
180f0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
18100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
18110 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
18120 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
18130 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
18140 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
18150 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
18160 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20  SQL text is.**  
18170 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f          read fro
18180 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  m zSql is read u
18190 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
181a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
181b0 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49  **.** {F13014} I
181c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
181d0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
181e0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
181f0 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
18200 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
18210 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
18220 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
18230 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  en nBytes bytes.
18240 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
18250 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f  text is read fro
18260 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  m zSql..**.** {F
18270 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74  13015} In [sqlit
18280 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
18290 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c  ,zSql,N,P,pzTail
182a0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
182b0 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nts.**          
182c0 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75  if the zSql inpu
182d0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
182e0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51  more than one SQ
182f0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  L statement.**  
18300 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61          and pzTa
18310 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  il is not NULL, 
18320 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
18330 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
18340 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
18350 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
18360 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
18370 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
18380 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20  ent in zSql..** 
18390 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57           <todo>W
183a0 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c  hat does *pzTail
183b0 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65   point to if the
183c0 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d  re is one statem
183d0 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  ent?</todo>.**.*
183e0 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63  * {F13016} A suc
183f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
18400 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18410 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70  _v2(db,zSql,N,pp
18420 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Stmt,...)].**   
18430 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66         or one of
18440 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72   its variants wr
18450 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d  ites into *ppStm
18460 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
18470 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
18480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
18490 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74  ment] or a point
184a0 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20  er to NULL.**   
184b0 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63         if zSql c
184c0 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20  ontains nothing 
184d0 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
184e0 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74  space or comment
184f0 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  s. .**.** {F1301
18500 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
18510 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
18520 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
18530 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
18540 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
18550 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
18560 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
18570 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
18580 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
18590 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
185a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
185b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
185c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
185d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
185e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
185f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
18600 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
18610 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
18620 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
18630 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
18640 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
18650 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
18660 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
18670 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
18680 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
18690 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
186a0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
186b0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
186c0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
186d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
186e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
186f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
18700 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
18710 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
18720 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
18730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
18740 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
18750 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
18760 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
18770 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
18780 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
18790 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
187a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
187b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
187c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
187d0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
187e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
187f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
18800 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
18810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
18820 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
18830 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
18840 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
18850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
18860 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
18870 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
18880 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
18890 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
188a0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
188b0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
188c0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
188d0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
188e0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
188f0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
18900 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
18910 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
18920 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
18930 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
18940 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
18950 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
18960 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
18970 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
18980 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
18990 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
189a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
189b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
189c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
189d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
189e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
189f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
18a00 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
18a10 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
18a20 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
18a30 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
18a40 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
18a50 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
18a60 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
18a70 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
18a80 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
18a90 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
18aa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
18ab0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
18ac0 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
18ad0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
18ae0 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20 75  ereface can be u
18af0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
18b00 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
18b10 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
18b20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
18b30 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
18b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
18b50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
18b60 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  :.**.** {F13101}
18b70 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
18b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
18b90 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
18ba0 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
18bb0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
18bc0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
18bd0 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
18be0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
18bf0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
18c00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
18c10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18c20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
18c30 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  2()],.**        
18c40 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
18c50 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
18c60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
18c70 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20  r to a.**       
18c80 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
18c90 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
18ca0 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
18cb0 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
18cc0 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
18cd0 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
18ce0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d  ..**.** {F13102}
18cf0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
18d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
18d10 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
18d20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
18d30 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
18d40 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
18d50 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
18d60 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
18d70 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
18d80 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
18d90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18da0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
18db0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
18dc0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
18dd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18de0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
18df0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d  ..**.** {F13103}
18e00 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
18e10 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
18e20 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
18e30 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
18e40 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
18e50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
18e60 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
18e70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
18e80 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
18e90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
18ea0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
18eb0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
18ec0 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
18ed0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
18ee0 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30  e Object  {F1500
18ef0 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
18f00 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
18f10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
18f20 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
18f30 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
18f40 65 20 6f 72 20 63 61 6e 20 62 65 20 73 74 6f 72  e or can be stor
18f50 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
18f60 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74   table..** SQLit
18f70 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
18f80 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61  yping for the va
18f90 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
18fa0 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72   .** Values stor
18fb0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
18fc0 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20  lue objects can 
18fd0 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72  be.** be integer
18fe0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
18ff0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
19000 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
19010 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  L..*/.typedef st
19020 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
19030 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
19040 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
19050 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
19060 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a  bject {F16001}.*
19070 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
19080 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
19090 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
190a0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
190b0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
190c0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
190d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
190e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
190f0 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61  * object is alwa
19100 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
19110 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
19120 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
19130 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65  nctions..*/.type
19140 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
19150 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
19160 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
19170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69  ** CAPI3REF:  Bi
19180 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
19190 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
191a0 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a  nts {F13500}.**.
191b0 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74  ** In the SQL st
191c0 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b  rings input to [
191d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
191e0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a  v2()] and its.**
191f0 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72   variants, liter
19200 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
19210 63 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ce by a paramete
19220 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74  r in one.** of t
19230 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a  hese forms:.**.*
19240 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
19250 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
19260 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
19270 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
19280 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
19290 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
192a0 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20  parameter forms 
192b0 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20  shown above NNN 
192c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  is an integer li
192d0 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c  teral,.** VVV al
192e0 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
192f0 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54  meter name..** T
19300 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
19310 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  se parameters (a
19320 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
19330 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
19340 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72  ".** or "SQL par
19350 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
19360 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
19370 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
19380 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
19390 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
193a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
193b0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
193c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
193d0 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73  nes always.** is
193e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
193f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19400 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
19410 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
19420 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
19430 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
19440 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   The second.** a
19450 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
19460 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 61  ndex of the para
19470 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
19480 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61   The.** first pa
19490 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
194a0 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e  ndex of 1.  When
194b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
194c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
194d0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
194e0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
194f0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
19500 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
19510 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
19520 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
19530 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69  rence. .** The i
19540 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
19550 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
19560 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
19570 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19580 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
19590 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64  name()] API if d
195a0 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
195b0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
195c0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
195d0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
195e0 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
195f0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
19600 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
19610 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
19620 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
19630 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
19640 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
19650 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61   999)..** See <a
19660 20 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74   href="limits.ht
19670 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c  ml">limits.html<
19680 2f 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  /a> for addition
19690 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
196a0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
196b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
196c0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
196d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
196e0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a  **.** In those.*
196f0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
19700 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
19710 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
19720 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
19730 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74  of bytes.** in t
19740 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
19750 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
19760 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
19770 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
19780 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20 76 61  /u>.** in the va
19790 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
197a0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
197b0 73 2e 20 20 20 54 68 65 20 6e 75 6d 62 65 72 0a  s.   The number.
197c0 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73  ** of bytes does
197d0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
197e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
197f0 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73   at the end of s
19800 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68  trings..** If th
19810 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
19820 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
19830 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
19840 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
19850 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
19860 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
19870 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
19880 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
19890 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
198a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
198b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
198c0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
198d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
198e0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
198f0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
19900 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
19910 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
19920 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
19930 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
19940 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
19950 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
19960 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
19970 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
19980 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
19990 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
199a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
199b0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
199c0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
199d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
199e0 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
199f0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
19a00 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
19a10 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
19a20 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
19a30 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
19a40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
19a50 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
19a60 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
19a70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
19a80 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
19a90 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
19aa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
19ab0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
19ac0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
19ad0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
19ae0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
19af0 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  eros.  A zeroblo
19b00 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
19b10 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
19b20 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
19b30 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73  ger to hold it s
19b40 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
19b50 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
19b60 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
19b70 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
19b80 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f  erve as place-ho
19b90 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
19ba0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
19bb0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
19bc0 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
19bd0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
19be0 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
19bf0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
19c00 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
19c10 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
19c20 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
19c30 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
19c40 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
19c50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
19c60 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
19c70 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
19c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19c90 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
19ca0 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
19cb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
19cc0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
19cd0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
19ce0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
19cf0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
19d00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
19d10 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
19d20 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
19d30 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
19d40 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
19d50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19d60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
19d70 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
19d80 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
19d90 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
19da0 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
19db0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
19dc0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
19dd0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
19de0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
19df0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
19e00 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
19e10 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
19e20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
19e30 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
19e40 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
19e50 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
19e60 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
19e70 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
19e80 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
19e90 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
19ea0 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
19eb0 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
19ec0 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
19ed0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
19ee0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
19ef0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
19f00 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
19f10 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
19f20 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
19f30 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
19f40 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
19f50 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
19f60 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
19f70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
19f80 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
19f90 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
19fa0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
19fb0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
19fc0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
19fd0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
19fe0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
19ff0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1a000 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1a010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1a020 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1a030 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a040 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36  S:.**.** {F13506
1a050 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1a060 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61  repare | SQL sta
1a070 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
1a080 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20   recognizes.**  
1a090 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f          tokens o
1a0a0 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c  f the forms "?",
1a0b0 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
1a0c0 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
1a0d0 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VV".**          
1a0e0 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
1a0f0 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20  s, where NNN is 
1a100 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1a110 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
1a120 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61          digits a
1a130 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
1a140 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1a150 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
1a160 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75           alphanu
1a170 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73  meric characters
1a180 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
1a190 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a  lly followed by.
1a1a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74  **          a st
1a1b0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1a1c0 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
1a1d0 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
1a1e0 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
1a1f0 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69  * {F13509} The i
1a200 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
1a210 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1a220 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1a230 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {F13512} The ind
1a240 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
1a250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1a260 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1a270 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
1a280 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
1a290 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1a2a0 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
1a2b0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1a2c0 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
1a2d0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1a2e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ter..**.** {F135
1a2f0 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
1a300 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
1a310 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1a320 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
1a330 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20  ** {F13518} The 
1a340 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
1a350 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
1a360 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
1a370 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
1a380 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
1a390 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
1a3a0 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20  most occurances 
1a3b0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1a3c0 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1a3d0 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1a3e0 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1a3f0 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1a400 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1a410 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1a420 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1a430 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63   first occurranc
1a440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1a450 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1a460 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1a470 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1a480 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1a490 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1a4a0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1a4b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1a4c0 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1a4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1a4e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1a4f0 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1a500 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1a510 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1a520 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1a530 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1a540 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1a550 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1a560 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1a570 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1a580 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1a590 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1a5a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1a5b0 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1a5c0 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1a5d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1a5e0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1a5f0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1a600 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1a610 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1a620 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1a630 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1a640 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1a650 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1a660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1a670 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1a680 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1a690 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1a6a0 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1a6b0 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1a6c0 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1a6d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1a6e0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1a6f0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1a700 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1a710 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1a720 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1a730 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1a740 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1a750 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1a760 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1a770 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1a780 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1a790 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1a7a0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1a7b0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1a7c0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1a7d0 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1a7e0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1a7f0 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1a800 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1a810 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1a820 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1a830 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1a840 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1a850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1a860 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1a870 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1a880 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1a890 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1a8a0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1a8b0 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1a8c0 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1a8d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1a8e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1a8f0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1a900 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1a910 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1a920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1a930 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1a940 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a950 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1a960 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1a970 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a980 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1a990 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1a9a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1a9b0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1a9c0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1a9d0 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1a9e0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1a9f0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1aa00 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1aa10 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1aa20 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1aa30 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1aa40 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1aa50 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1aa60 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1aa70 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1aa80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1aa90 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1aaa0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1aab0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1aac0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1aad0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1aae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1aaf0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1ab00 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1ab10 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1ab20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1ab30 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1ab40 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1ab50 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1ab60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1ab70 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1ab80 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1ab90 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1aba0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1abb0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1abc0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1abd0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1abe0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1abf0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1ac00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1ac10 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1ac20 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1ac30 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1ac40 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1ac50 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1ac60 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1ac70 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1ac80 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1ac90 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1aca0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1acb0 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1acc0 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1acd0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1ace0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1acf0 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1ad00 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1ad10 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1ad20 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1ad30 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1ad40 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1ad50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1ad60 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1ad70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1ad80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1ad90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1ada0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1adb0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1adc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1add0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1ade0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1adf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1ae00 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1ae10 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1ae20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1ae30 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1ae40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ae50 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1ae60 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1ae70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ae80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1ae90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1aea0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1aeb0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1aec0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1aed0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1aee0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1aef0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1af00 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1af10 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1af20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1af30 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1af40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1af50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1af60 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1af70 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1af80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1af90 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1afa0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33   Parameters {F13
1afb0 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600}.**.** This 
1afc0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1afd0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1afe0 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61  number of SQL pa
1aff0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61  rameters.** in a
1b000 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1b010 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  ent.  SQL parame
1b020 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
1b030 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
1b040 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
1b050 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
1b060 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
1b070 20 61 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f 6c   as.** place-hol
1b080 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
1b090 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
1b0a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
1b0b0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
1b0c0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
1b0d0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
1b0e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63   This routine ac
1b0f0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1b100 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1b110 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74 65  largest paramete
1b120 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f  r..** For all fo
1b130 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
1b140 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
1b150 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d  spond to the num
1b160 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65  ber of.** unique
1b170 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
1b180 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1b190 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
1b1a0 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62  , there may.** b
1b1b0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
1b1c0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
1b1d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1b1e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1b1f0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1b200 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b210 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
1b220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b230 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1b240 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1b250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1b260 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3601} The [sqlit
1b270 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b280 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  r_count(S)] inte
1b290 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1b2a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61            the la
1b2b0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61  rgest index of a
1b2c0 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
1b2d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
1b2e0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1b2f0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
1b300 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20  0 if S.**       
1b310 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53     contains no S
1b320 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  QL parameters..*
1b330 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1b340 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1b350 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1b360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b370 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
1b380 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31  st Parameter {F1
1b390 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3620}.**.** This
1b3a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b3b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1b3c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
1b3d0 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  th.** SQL parame
1b3e0 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72  ter in a [prepar
1b3f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1b400 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1b410 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41   of the form ":A
1b420 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1b430 20 22 24 41 41 41 22 20 68 61 76 65 20 61 20 6e   "$AAA" have a n
1b440 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ame.** which is 
1b450 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41  the string ":AAA
1b460 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1b470 24 56 56 56 22 2e 20 0a 2a 2a 20 49 6e 20 6f 74  $VVV". .** In ot
1b480 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
1b490 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
1b4a0 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69  " or "@".** is i
1b4b0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
1b4c0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  of the name..** 
1b4d0 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
1b4e0 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f  e form "?" or "?
1b4f0 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d  NNN" have no nam
1b500 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
1b510 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
1b520 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1b530 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
1b540 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
1b550 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b560 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
1b570 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1b580 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
1b590 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1b5a0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
1b5b0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
1b5c0 79 73 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20  ys in the UTF-8 
1b5d0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
1b5e0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
1b5f0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
1b600 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
1b610 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
1b620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1b630 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1b640 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1b650 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1b660 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1b670 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1b680 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1b690 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b6a0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1b6b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1b6c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1b6d0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1b6e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1b6f0 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
1b700 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b710 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
1b720 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1b730 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
1b740 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1b750 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1b760 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1b770 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  n.**          [p
1b780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b790 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
1b7a0 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
1b7b0 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
1b7c0 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
1b7d0 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
1b7e0 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
1b7f0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
1b800 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
1b810 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
1b820 70 61 72 61 6d 65 74 65 72 20 22 3f 22 20 6f 72  parameter "?" or
1b830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e  .**          a n
1b840 75 6d 62 65 72 65 64 20 70 61 72 61 6d 65 74 65  umbered paramete
1b850 72 20 22 3f 4e 4e 4e 22 2e 0a 2a 2f 0a 63 6f 6e  r "?NNN"..*/.con
1b860 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1b870 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1b880 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1b890 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
1b8a0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
1b8b0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
1b8c0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
1b8d0 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a  e {F13640}.**.**
1b8e0 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65   Return the inde
1b8f0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1b900 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
1b910 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  name.  The.** in
1b920 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1b930 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1b940 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1b950 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1b960 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1b970 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1b980 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f  bind()].  A zero
1b990 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1b9a0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
1b9b0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
1b9c0 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65  d.  The paramete
1b9d0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
1b9e0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
1b9f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
1ba00 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
1ba10 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
1ba20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
1ba30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ba40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1ba50 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1ba60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1ba70 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1ba80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ba90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1baa0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1bab0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1bac0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1bad0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1bae0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1baf0 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
1bb00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1bb10 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65  index(S,N)] inte
1bb20 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1bb30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e            the in
1bb40 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
1bb50 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65  eter in [prepare
1bb60 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
1bb70 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
1bb80 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
1bb90 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
1bba0 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
1bbb0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
1bbc0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
1bbd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1bbe0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
1bbf0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
1bc00 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
1bc10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bc20 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
1bc30 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
1bc40 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
1bc50 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  660}.**.** Contr
1bc60 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
1bc70 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
1bc80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1bc90 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65  does not.** rese
1bca0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  t the [sqlite3_b
1bcb0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
1bcc0 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70  ngs] on a .** [p
1bcd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1bce0 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f  t].  Use this ro
1bcf0 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65  utine to.** rese
1bd00 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1bd10 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1bd20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1bd30 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20  .**.** {F13661} 
1bd40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
1bd50 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
1bd60 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
1bd70 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
1bd80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62   SQL parameter b
1bd90 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70  indings in [prep
1bda0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1bdb0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
1bdc0 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  ck to NULL..*/.i
1bdd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
1bde0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
1bdf0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1be00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1be10 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
1be20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
1be30 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3710}.**.** Retu
1be40 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
1be50 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
1be60 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
1be70 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b  ned by the .** [
1be80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1be90 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
1bea0 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
1beb0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
1bec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
1bed0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
1bee0 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
1bef0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
1bf00 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1bf10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1bf20 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1bf30 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
1bf40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1bf50 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1bf60 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  f.**          co
1bf70 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1bf80 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65  ult set generate
1bf90 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
1bfa0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1bfb0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
1bfc0 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20  0 if S does not 
1bfd0 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20  generate.**     
1bfe0 20 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65       a result se
1bff0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
1c000 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
1c010 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1c020 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1c030 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
1c040 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
1c050 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a  et {F13720}.**.*
1c060 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c070 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1c080 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
1c090 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
1c0a0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
1c0b0 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1c0c0 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  T statement.  Th
1c0d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
1c0e0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
1c0f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
1c100 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
1c110 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38  -terminated UTF8
1c120 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
1c130 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1c140 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
1c150 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1c160 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c170 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
1c180 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1c190 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70  ter is the.** [p
1c1a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c1b0 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
1c1c0 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
1c1d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
1c1e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c1f0 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
1c200 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
1c210 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
1c220 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
1c230 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
1c240 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
1c250 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
1c260 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72  ther the .** [pr
1c270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c280 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  ] is destroyed b
1c290 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
1c2a0 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74  ize()].** or unt
1c2b0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
1c2c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1c2d0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1c2e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c2f0 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  ).** on the same
1c300 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
1c310 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1c320 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
1c330 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
1c340 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
1c350 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
1c360 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
1c370 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
1c380 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
1c390 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1c3a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1c3b0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
1c3c0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1c3d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1c3e0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
1c3f0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
1c400 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
1c410 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
1c420 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
1c430 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
1c440 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1c450 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
1c460 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
1c470 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
1c480 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
1c490 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
1c4a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1c4b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31  S:.**.** {F13721
1c4c0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
1c4d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
1c4e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1c4f0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
1c500 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1c510 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
1c520 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
1c530 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1c540 20 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65   (where 0 is the
1c550 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
1c560 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  n) for the.**   
1c570 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
1c580 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
1c590 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
1c5a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1c5b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1c5c0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1c5d0 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63   {F13723} A succ
1c5e0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1c5f0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
1c600 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c610 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
1c620 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
1c630 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  rns the name.** 
1c640 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1c650 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
1c660 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d  e 0 is the left-
1c670 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
1c680 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c690 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
1c6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c6b0 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20  nt] S as a.**   
1c6c0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1c6d0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
1c6e0 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69  ring in the nati
1c6f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1c700 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68  *.** {F13724} Th
1c710 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1c720 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
1c730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1c740 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
1c750 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
1c760 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
1c770 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
1c780 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
1c790 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
1c7a0 6d 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20 74 6f  memory memory to
1c7b0 20 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f 72 6d   hold there norm
1c7c0 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67  al return string
1c7d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35  s..**.** {F13725
1c7e0 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d  } If the N param
1c7f0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c800 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
1c810 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1c820 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
1c830 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
1c840 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
1c850 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  then the.**     
1c860 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
1c870 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1c880 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b  ointer..** .** {
1c890 46 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69  F13726} The stri
1c8a0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c8b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c8c0 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a  name(S,N)] and.*
1c8d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c8e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1c8f0 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69  6(S,N)] are vali
1c900 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
1c910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
1c920 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74  l to either rout
1c930 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d  ine with the sam
1c940 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65  e S and N parame
1c950 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
1c960 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
1c970 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
1c980 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  is called..**.**
1c990 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61   {F13727} When a
1c9a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1c9b0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
1c9c0 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a  tement contains.
1c9d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41  **          an A
1c9e0 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61  S clause, the na
1c9f0 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d  me of that colum
1ca00 6e 20 69 73 20 74 68 65 20 69 6e 64 65 6e 74 69  n is the indenti
1ca10 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
1ca20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
1ca30 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
1ca40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ca50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1ca60 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1ca70 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
1ca80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1ca90 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
1caa0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1cab0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
1cac0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
1cad0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
1cae0 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a  esult {F13740}.*
1caf0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1cb00 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
1cb10 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
1cb20 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
1cb30 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
1cb40 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
1cb50 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45  a result of a SE
1cb60 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63  LECT statement c
1cb70 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
1cb80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1cb90 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
1cba0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
1cbb0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
1cbc0 65 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72  either a UTF8 or
1cbd0 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
1cbe0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
1cbf0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
1cc00 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
1cc10 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
1cc20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1cc30 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
1cc40 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
1cc50 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
1cc60 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
1cc70 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
1cc80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1cc90 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68  alid until.** th
1cca0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1ccb0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
1ccc0 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
1ccd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1cce0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
1ccf0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1cd00 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
1cd10 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
1cd20 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
1cd30 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
1cd40 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
1cd50 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
1cd60 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
1cd70 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
1cd80 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
1cd90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1cda0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1cdb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
1cdc0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
1cdd0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
1cde0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
1cdf0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
1ce00 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
1ce10 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
1ce20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
1ce30 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
1ce40 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
1ce50 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
1ce60 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
1ce70 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
1ce80 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
1ce90 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
1cea0 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79  n.** or subquery
1ceb0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
1cec0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
1ced0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
1cee0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
1cef0 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  n NULL.  These r
1cf00 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
1cf10 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
1cf20 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
1cf30 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
1cf40 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
1cf50 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
1cf60 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  e .** name of th
1cf70 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
1cf80 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63  ase, table and c
1cf90 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
1cfa0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
1cfb0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
1cfc0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
1cfd0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
1cfe0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
1cff0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
1d000 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
1d010 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
1d020 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
1d030 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1d040 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
1d050 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
1d060 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1d070 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1d080 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1d090 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
1d0a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1d0b0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
1d0c0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1d0d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  fined..**.** {U1
1d0e0 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
1d0f0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1d100 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1d110 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1d120 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
1d130 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
1d140 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1d150 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
1d160 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1d170 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
1d180 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
1d190 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d1a0 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73   {F13741} The [s
1d1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1d1c0 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29  tabase_name(S,N)
1d1d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d1e0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1d1f0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
1d200 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d210 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1d220 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  abase from which
1d230 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1d240 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1d250 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1d260 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1d270 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1d280 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1d290 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1d2a0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1d2b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1d2c0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1d2d0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1d2e0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1d2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1d300 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1d310 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1d320 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  F13742} The [sql
1d330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1d340 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
1d350 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d360 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1d370 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1d380 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1d390 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1d3a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d3b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1d3c0 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
1d3d0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1d3e0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1d3f0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1d400 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1d410 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1d420 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1d430 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1d440 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1d450 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1d460 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1d470 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1d480 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1d490 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1d4a0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1d4b0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1d4c0 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  13743} The [sqli
1d4d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1d4e0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1d4f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1d500 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1d510 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
1d520 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1d530 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
1d540 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1d550 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1d560 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1d570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d580 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1d590 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1d5a0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74  or NULL if the t
1d5b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1d5c0 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
1d5d0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
1d5e0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
1d5f0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d600 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
1d610 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
1d620 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
1d630 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54    .** {F13744} T
1d640 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1d650 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1d660 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1d670 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
1d680 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
1d690 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
1d6a0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
1d6b0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1d6c0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1d6d0 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1d6e0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1d6f0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1d700 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1d710 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1d720 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1d730 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1d740 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1d750 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1d760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1d770 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1d780 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1d790 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1d7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1d7b0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1d7c0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1d7d0 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  F13745} The [sql
1d7e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1d7f0 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
1d800 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1d810 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1d820 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1d830 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1d840 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1d850 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
1d860 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1d870 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1d880 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1d890 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1d8a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1d8b0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1d8c0 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1d8d0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1d8e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1d8f0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1d900 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1d910 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1d920 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1d930 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1d940 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1d950 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c  F13746} The [sql
1d960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1d970 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  in_name16(S,N)] 
1d980 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1d990 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1d9a0 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
1d9b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d9c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
1d9d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
1d9e0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
1d9f0 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
1da00 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1da10 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1da20 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1da30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1da40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1da50 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1da60 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1da70 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1da80 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1da90 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1daa0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1dab0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1dac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1dad0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1dae0 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1daf0 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {F13748} The ret
1db00 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
1db10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1db20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1db30 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1db40 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1db50 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1db60 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20    are valid.**  
1db70 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
1db80 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1db90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1dba0 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
1dbb0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e   or until the en
1dbc0 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65  coding is change
1dbd0 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74  d by another met
1dbe0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
1dbf0 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c    interface call
1dc00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72   for the same pr
1dc10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dc20 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
1dc30 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
1dc40 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49  **.** {U13751} I
1dc50 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
1dc60 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
1dc70 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
1dc80 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1dc90 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1dca0 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
1dcb0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
1dcc0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
1dcd0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1dce0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
1dcf0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  t column.**     
1dd00 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65       at the same
1dd10 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1dd20 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
1dd30 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
1dd40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1dd50 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1dd60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1dd70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1dd80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1dd90 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
1dda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1ddb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1ddc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1ddd0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
1dde0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1ddf0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1de00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1de10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1de20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1de30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1de40 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1de50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1de60 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1de70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1de80 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
1de90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1dea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1deb0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
1dec0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
1ded0 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d   Result {F13760}
1dee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1def0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1df00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1df10 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69  ent]. .** If thi
1df20 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
1df30 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1df40 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
1df50 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20  lumn of the .** 
1df60 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
1df70 73 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45  set of that SELE
1df80 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  CT is a table co
1df90 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
1dfa0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1dfb0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
1dfc0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
1dfd0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
1dfe0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
1dff0 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
1e000 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
1e010 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
1e020 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
1e030 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
1e040 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1e050 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
1e060 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1e070 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
1e080 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d   encoded.  {END}
1e090 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65   .** For example
1e0a0 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  , in the databas
1e0b0 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
1e0c0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
1e0d0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
1e0e0 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** And the follo
1e0f0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  wing statement c
1e100 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
1e110 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
1e120 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
1e130 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  Then this routin
1e140 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
1e150 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
1e160 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
1e170 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c  nd.** result col
1e180 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
1e190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
1e1a0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
1e1b0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69  ult column.** (i
1e1c0 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e1d0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e1e0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e1f0 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e200 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e210 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e220 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e230 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e240 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e250 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e260 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e270 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e280 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e290 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e2a0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e2b0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e2c0 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e2d0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1e2e0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1e2f0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1e300 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1e310 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1e320 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1e330 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1e340 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20  **.** {F13761}  
1e350 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1e360 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
1e370 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
1e380 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
1e390 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d   returns a zero-
1e3a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1e3b0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1e3c0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
1e3d0 20 20 20 20 74 68 65 20 64 65 63 6c 61 72 65 64      the declared
1e3e0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
1e3f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1e400 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20  at appears.**   
1e410 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e          as the N
1e420 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
1e430 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74  red from 0) of t
1e440 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
1e450 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e460 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1e470 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
1e480 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {F13762}  A succ
1e490 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1e4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1e4b0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
1e4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
1e4d0 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
1e4e0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
1e4f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1e500 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
1e510 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
1e520 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
1e530 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
1e540 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
1e550 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
1e560 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
1e570 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
1e580 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
1e590 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
1e5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
1e5b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e5c0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
1e5d0 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
1e5e0 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
1e5f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
1e600 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
1e610 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
1e620 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e640 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
1e650 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74      or if the Nt
1e660 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1e670 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1e680 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65  r subquery rathe
1e690 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
1e6a0 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75  han a table colu
1e6b0 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  mn or if a memor
1e6c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1e6d0 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
1e6e0 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
1e6f0 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
1e700 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
1e710 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
1e720 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e730 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
1e740 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
1e750 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e760 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
1e770 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
1e780 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1e790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1e7a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
1e7b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1e7c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e7d0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
1e7e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e7f0 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33  );../* .** CAPI3
1e800 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41  REF:  Evaluate A
1e810 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1e820 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F13200}.**.** A
1e830 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65  fter an [prepare
1e840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
1e850 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 77   been prepared w
1e860 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f  ith a call.** to
1e870 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1e880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e890 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e8a0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f  re16_v2()] or to
1e8b0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c   one of.** the l
1e8c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
1e8d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e8e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1e8f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
1e900 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63  * then this func
1e910 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c  tion must be cal
1e920 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
1e930 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
1e940 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d  e the .** statem
1e950 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
1e960 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
1e970 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73  havior of this s
1e980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1e990 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
1e9a0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
1e9b0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
1e9c0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
1e9d0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
1e9e0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
1e9f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ea00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1ea10 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
1ea20 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
1ea30 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
1ea40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ea50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ea60 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
1ea70 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
1ea80 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
1ea90 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1eaa0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
1eab0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
1eac0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1ead0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
1eae0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
1eaf0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
1eb00 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  lagacy interface
1eb10 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1eb20 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
1eb30 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
1eb40 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e   .** [SQLITE_DON
1eb50 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
1eb60 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
1eb70 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
1eb80 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
1eb90 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1eba0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
1ebb0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  er [SQLITE_OK | 
1ebc0 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
1ebd0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1ebe0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
1ebf0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69   result code] mi
1ec00 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
1ec10 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  as.** well..**.*
1ec20 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1ec30 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1ec40 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1ec50 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1ec60 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1ec70 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1ec80 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1ec90 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1eca0 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54  ment is a COMMIT
1ecb0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
1ecc0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
1ecd0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1ece0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
1ecf0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
1ed00 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
1ed10 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
1ed20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63  a COMMIT and occ
1ed30 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
1ed40 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1ed50 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
1ed60 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
1ed70 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
1ed80 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
1ed90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
1eda0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
1edb0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
1edc0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
1edd0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
1ede0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
1edf0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
1ee00 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
1ee10 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
1ee20 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
1ee30 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
1ee40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
1ee50 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
1ee60 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
1ee70 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
1ee80 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
1ee90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
1eea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
1eeb0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
1eec0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
1eed0 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  en .** [SQLITE_R
1eee0 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OW] is returned 
1eef0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
1ef00 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
1ef10 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63  eady.** for proc
1ef20 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61  essing by the ca
1ef30 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
1ef40 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
1ef50 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
1ef60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
1ef70 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73  t | column acces
1ef80 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
1ef90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1efa0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
1efb0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
1efc0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
1efd0 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  ..** .** [SQLITE
1efe0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
1eff0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
1f000 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
1f010 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
1f020 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
1f030 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
1f040 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
1f050 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
1f060 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
1f070 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
1f080 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
1f090 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1f0a0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57  _errmsg()]..** W
1f0b0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
1f0c0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
1f0d0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
1f0e0 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a  code (example:.*
1f0f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
1f100 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
1f110 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
1f120 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
1f130 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
1f140 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
1f150 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
1f160 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
1f170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f180 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
1f190 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
1f1a0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
1f1b0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
1f1c0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
1f1d0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
1f1e0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
1f1f0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
1f200 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
1f210 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
1f220 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
1f230 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
1f240 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
1f250 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f260 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
1f270 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
1f280 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f290 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
1f2a0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
1f2b0 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ad .** previousl
1f2c0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
1f2d0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
1f2e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
1f2f0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
1f300 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
1f310 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1f320 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
1f330 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
1f340 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
1f350 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
1f360 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
1f370 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
1f380 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
1f390 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  >.** In the lega
1f3a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a  cy interface, .*
1f3b0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  * the sqlite3_st
1f3c0 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20  ep() API always 
1f3d0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
1f3e0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a  c error code,.**
1f3f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1f400 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65   following any e
1f410 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
1f420 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1f430 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
1f440 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
1f450 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65  call [sqlite3_re
1f460 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
1f470 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1f480 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
1f490 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70  nd one of the sp
1f4a0 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72  ecific.** [error
1f4b0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
1f4c0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
1f4d0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
1f4e0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
1f4f0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
1f500 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
1f510 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
1f520 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
1f530 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
1f540 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
1f550 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
1f560 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
1f570 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1f580 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1f590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f5a0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
1f5b0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
1f5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f5d0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1f5e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
1f5f0 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72  then the .** mor
1f600 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1f610 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1f620 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1f630 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1f640 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1f650 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f660 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f670 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
1f680 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1f690 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72  202}  If [prepar
1f6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f6b0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a  is ready to be.*
1f6c0 2a 20 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c  *           run,
1f6d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1f6e0 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
1f6f0 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
1f700 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
1f710 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63        until to c
1f720 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74  ompletion or unt
1f730 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74  il it is ready t
1f740 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72  o return another
1f750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f  .**           ro
1f760 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
1f770 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  set or an interr
1f780 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  upt or run-time 
1f790 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
1f7a0 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68  .** {F15304}  Wh
1f7b0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
1f7c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
1f7d0 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20  auses the .**   
1f7e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74  d statement] S t
1f800 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
1f810 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion,.**         
1f820 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    the function r
1f830 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1f840 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ONE]..**.** {F15
1f850 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  306}  When a cal
1f860 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1f870 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63  ep(S)] stops bec
1f880 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79  ause it is ready
1f890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
1f8a0 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
1f8b0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
1f8c0 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e  t set, it return
1f8d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
1f8e0 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
1f8f0 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20  ** {F15308}  If 
1f900 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
1f910 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
1f920 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
1f930 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f940 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72  interrupt|interr
1f950 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
1f960 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
1f970 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
1f980 73 20 61 6e 20 61 70 70 72 6f 70 72 61 69 74 65  s an appropraite
1f990 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
1f9a0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
1f9b0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
1f9c0 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
1f9d0 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
1f9e0 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
1f9f0 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  F15310}  If an [
1fa00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1fa10 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  t|interrupt] or 
1fa20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a  run-time error.*
1fa30 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
1fa40 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c  rs during a call
1fa50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
1fa60 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  p(S)].**        
1fa70 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72     for a [prepar
1fa80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1fa90 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
1faa0 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63             legac
1fab0 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
1fac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1fad0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1fae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1faf0 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20  e16()] then the 
1fb00 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1fb10 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1fb20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
1fb30 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
1fb40 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
1fb50 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
1fb60 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
1fb70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1fb80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1fb90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1fba0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
1fbb0 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13770}.**.** Re
1fbc0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1fbd0 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
1fbe0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
1fbf0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
1fc00 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1fc10 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d  :.**.** {F13771}
1fc20 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74    After a call t
1fc30 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
1fc40 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  S)] that returns
1fc50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
1fc60 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
1fc70 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
1fc80 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a  unt(S)] routine.
1fc90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77 69 6c  **           wil
1fca0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
1fcb0 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a  e value as the.*
1fcc0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
1fcd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
1fce0 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  t(S)] function..
1fcf0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20  **.** {F13772}  
1fd00 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
1fd10 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
1fd20 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
1fd30 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
1fd40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
1fd50 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  OW] or before [s
1fd60 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
1fd70 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20  has been .**    
1fd80 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e         called on
1fd90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1fda0 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a  tatement] for.**
1fdb0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
1fdc0 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20  irst time since 
1fdd0 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f  it was [sqlite3_
1fde0 70 72 65 70 61 72 65 7c 70 72 65 70 61 72 65 64  prepare|prepared
1fdf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ].**           o
1fe00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
1fe10 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71  |reset], the [sq
1fe20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
1fe30 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
1fe40 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e    routine return
1fe50 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
1fe60 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
1fe70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1fe80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1fe90 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
1fea0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
1feb0 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f  F10265}.** KEYWO
1fec0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
1fed0 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45  .**.** {F10266}E
1fee0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
1fef0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
1ff00 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
1ff10 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
1ff20 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
1ff30 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
1ff40 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
1ff50 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
1ff60 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
1ff70 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
1ff80 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
1ff90 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
1ffa0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
1ffb0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
1ffc0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
1ffd0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
1ffe0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1fff0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
20000 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
20010 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
20020 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
20030 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
20040 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
20050 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
20060 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
20070 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
20080 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
20090 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
200a0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
200b0 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  TEXT not.** SQLI
200c0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
200d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
200e0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
200f0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
20100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
20110 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
20120 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
20130 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
20140 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
20150 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
20160 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
20170 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
20180 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
20190 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
201a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
201b0 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72  esults Values Fr
201c0 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38  om A Query {F138
201d0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
201e0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
201f0 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
20200 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
20210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
20220 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
20230 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a  rmation about.**
20240 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
20250 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
20260 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
20270 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
20280 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72  .** case the fir
20290 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
202a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
202b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
202c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
202d0 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61   being.** evalua
202e0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
202f0 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61  3_stmt*] that wa
20300 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
20310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20320 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
20330 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
20340 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65  s) and.** the se
20350 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
20360 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
20370 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
20380 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a  ch information .
20390 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
203a0 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
203b0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  -most column of 
203c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  the result set.*
203d0 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  * has an index o
203e0 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  f 0..**.** If th
203f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20400 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
20410 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
20420 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
20430 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69  .** the column i
20440 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
20450 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
20460 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a   is undefined. .
20470 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20480 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
20490 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
204a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
204b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
204c0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
204d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
204e0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
204f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20500 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
20510 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65  nalize()] has be
20520 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65  en call subseque
20530 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
20540 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20550 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
20560 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
20570 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
20580 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
20590 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
205a0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
205b0 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
205c0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
205d0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
205e0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
205f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
20600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
20610 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
20620 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20630 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
20640 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
20650 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
20660 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
20670 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
20680 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
20690 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
206a0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a  re undefined.  .
206b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
206c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
206d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
206e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
206f0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
20700 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
20710 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
20720 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
20730 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
20740 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
20750 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
20760 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
20770 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
20780 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
20790 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
207a0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
207b0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
207c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
207d0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
207e0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
207f0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
20800 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
20810 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
20820 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
20830 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
20840 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
20850 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
20860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
20870 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
20880 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
20890 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
208a0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
208b0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
208c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
208d0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
208e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
208f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
20900 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
20910 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
20920 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
20930 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a  olumn_bytes() .*
20940 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
20950 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20960 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
20970 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
20980 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
20990 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
209a0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
209b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
209c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
209d0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
209e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
209f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20a00 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
20a10 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
20a20 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
20a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
20a40 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
20a50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20a60 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
20a70 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
20a80 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
20a90 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
20aa0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
20ab0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
20ac0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20ad0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
20ae0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
20af0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
20b00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
20b10 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
20b20 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
20b30 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
20b40 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
20b50 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
20b60 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
20b70 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
20b80 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
20b90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
20ba0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
20bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20bc0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
20bd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
20be0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
20bf0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
20c00 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
20c10 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
20c20 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
20c30 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
20c40 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72  lob is an arbitr
20c50 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
20c60 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
20c70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
20c80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20c90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
20ca0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
20cb0 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
20cc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
20cd0 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
20ce0 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
20cf0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
20d00 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
20d10 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65   UTF-8.  .** The
20d20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
20d30 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
20d40 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
20d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
20d60 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
20d70 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
20d80 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
20d90 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
20da0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
20db0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
20dc0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
20dd0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
20de0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
20df0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
20e00 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
20e10 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74  ternally to do t
20e20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  he conversion.**
20e30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
20e40 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
20e50 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
20e60 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61   conversions tha
20e70 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64  t.** are applied
20e80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
20e90 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
20ea0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
20eb0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
20ec0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
20ed0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
20ee0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
20ef0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
20f00 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
20f10 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
20f20 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
20f30 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20f40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
20f50 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
20f60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
20f70 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
20f80 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
20f90 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
20fa0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
20fb0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
20fc0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
20fd0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
20fe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
20ff0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
21000 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
21010 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
21020 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
21030 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
21040 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
21050 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
21060 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
21070 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
21080 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
21090 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66    <td> Same as f
210a0 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  or INTEGER->TEXT
210b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
210c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
210d0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
210e0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
210f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
21100 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
21110 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
21120 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
21130 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
21140 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
21150 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
21160 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
21170 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
21180 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
21190 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
211a0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
211b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
211c0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
211d0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
211e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
211f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
21200 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
21210 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
21220 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
21230 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
21240 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
21250 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
21260 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
21270 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
21280 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
21290 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
212a0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
212b0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
212c0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
212d0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
212e0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
212f0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
21300 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
21310 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
21320 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
21330 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
21340 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
21350 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
21360 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
21370 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
21380 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
21390 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
213a0 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c  ts.** on equaval
213b0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
213c0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
213d0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
213e0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
213f0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
21400 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
21410 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
21420 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
21430 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
21440 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
21450 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
21460 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
21470 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
21480 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
21490 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
214a0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
214b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
214c0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
214d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
214e0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
214f0 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70  lidated. .** Typ
21500 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
21510 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
21520 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
21530 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
21540 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
21550 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
21560 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
21570 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
21580 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
21590 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a  column_text() .*
215a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71  *          or sq
215b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
215c0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
215d0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
215e0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
215f0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
21600 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
21610 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  ring.</p></li>.*
21620 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
21630 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
21640 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
21650 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
21660 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
21670 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69  **          sqli
21680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
21690 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
216a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
216b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
216c0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
216d0 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  -16.</p></li>.**
216e0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
216f0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
21700 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
21710 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
21720 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
21730 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
21740 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
21750 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
21760 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
21770 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
21780 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
21790 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  /p></li>.** </ul
217a0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
217b0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
217c0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
217d0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
217e0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
217f0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
21800 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
21810 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
21820 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
21830 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
21840 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
21850 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
21860 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
21870 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
21880 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
21890 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
218a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
218b0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
218c0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69  , but sometime i
218d0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
218e0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
218f0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
21900 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
21910 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  idated.  .**.** 
21920 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
21930 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
21940 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
21950 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
21960 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
21970 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
21980 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75   ways:.**.**  <u
21990 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
219a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
219b0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
219c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
219d0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
219e0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
219f0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
21a00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
21a10 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
21a20 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
21a30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
21a40 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
21a50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
21a60 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75  6()</li>.**  </u
21a70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
21a80 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
21a90 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
21aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
21ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21ac0 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c  lob(),.** or sql
21ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21ae0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
21af0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69  rce the result i
21b00 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a  nto the desired.
21b10 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ** format, then 
21b20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
21b30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
21b40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21b50 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20  bytes16() to.** 
21b60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
21b70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
21b80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f   not mix call to
21b90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21ba0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  text() or.** sql
21bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
21bc0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
21bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21be0 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20  bytes16().  And 
21bf0 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61  do not.** mix ca
21c00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21c10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77  olumn_text16() w
21c20 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
21c30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21c40 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
21c50 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
21c60 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
21c70 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
21c80 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
21c90 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
21ca0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
21cb0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
21cc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21cd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21ce0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
21cf0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
21d00 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
21d10 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
21d20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65  and blobs is fre
21d30 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
21d40 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
21d50 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
21d60 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
21d70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21d80 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
21d90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
21da0 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b   etc. into .** [
21db0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
21dc0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
21dd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
21de0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
21df0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
21e00 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
21e10 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
21e20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
21e30 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21e40 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
21e50 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
21e60 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
21e70 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
21e80 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
21e90 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
21ea0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
21eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
21ec0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
21ed0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
21ee0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
21ef0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
21f00 46 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  F13803} The [sql
21f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
21f20 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
21f30 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
21f40 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
21f50 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
21f60 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
21f70 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
21f80 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
21f90 72 65 64 5f 73 74 61 74 65 6d 65 6e 74 5d 20 53  red_statement] S
21fa0 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64   into a blob and
21fb0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
21fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
21fd0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
21fe0 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
21ff0 2a 20 7b 46 31 33 38 30 36 7d 20 54 68 65 20 5b  * {F13806} The [
22000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22010 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ytes(S,N)] inter
22020 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
22030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
22040 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
22050 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72 69  the blob or stri
22060 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
22070 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22080 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
22090 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
220a0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
220b0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
220c0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
220d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
220e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
220f0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
22100 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
22110 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a  mn_text(S,N)]..*
22120 2a 0a 2a 2a 20 7b 46 31 33 38 30 39 7d 20 54 68  *.** {F13809} Th
22130 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22140 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20  n_bytes16(S,N)] 
22150 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22160 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22170 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
22180 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
22190 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
221a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
221b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
221c0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
221d0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
221e0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
221f0 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
22200 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
22210 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
22220 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  )]..**.** {F1381
22230 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
22240 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c  column_double(S,
22250 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
22260 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
22270 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
22280 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
22290 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
222a0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
222b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
222c0 5f 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e  _statement] S in
222d0 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
222e0 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
222f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
22300 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
22310 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
22320 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  13815} The [sqli
22330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53  te3_column_int(S
22340 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
22350 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
22360 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
22370 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
22380 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
22390 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
223a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
223b0 64 5f 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d_statement] S i
223c0 6e 74 6f 20 61 20 33 32 2d 62 69 74 20 73 69 67  nto a 32-bit sig
223d0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
223e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
223f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
22400 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
22410 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b  * {F13818} The [
22420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
22430 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
22440 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
22450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
22460 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
22470 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
22480 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
22490 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
224a0 72 65 70 61 72 65 64 5f 73 74 61 74 65 6d 65 6e  repared_statemen
224b0 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
224c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
224d0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
224e0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
224f0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
22500 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d  ..**.** {F13821}
22510 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
22520 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
22530 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
22540 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
22550 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
22560 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
22570 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
22580 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
22590 20 20 20 5b 70 72 65 70 61 72 65 64 5f 73 74 61     [prepared_sta
225a0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
225b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
225c0 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20   UTF-8 .**      
225d0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
225e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
225f0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
22600 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20  .**.** {F13824} 
22610 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
22620 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
22630 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
22640 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
22650 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
22660 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
22670 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
22680 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
22690 20 20 20 20 5b 70 72 65 70 61 72 65 64 5f 73 74      [prepared_st
226a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
226b0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
226c0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
226d0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
226e0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
226f0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
22700 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
22710 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
22720 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
22730 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68  *.** {F13827} Th
22740 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22750 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
22760 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
22770 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
22780 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
22790 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
227a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 45 41 4c 5d  ], [SQLITE_REAL]
227b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
227c0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
227d0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
227e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
227f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
22800 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
22810 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
22820 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22830 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
22840 20 5b 70 72 65 70 61 72 65 64 5f 73 74 61 74 65   [prepared_state
22850 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
22860 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  F13830} The [sql
22870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
22880 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
22890 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
228a0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
228b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
228c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 74 68  value] object th
228d0 61 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  at for the.**   
228e0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
228f0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
22900 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
22910 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
22920 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22930 5f 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a  _statement] S..*
22940 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
22950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
22960 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
22970 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
22980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22990 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
229a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
229b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
229c0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
229d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
229e0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
229f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
22a00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22a10 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
22a20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
22a30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
22a40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
22a50 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
22a60 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
22a70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22a80 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
22a90 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
22aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
22ab0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
22ac0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
22ad0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22ae0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
22af0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22b00 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
22b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22b20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22b30 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
22b40 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
22b50 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
22b60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22b70 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
22b80 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
22b90 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
22ba0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
22bb0 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3300}.**.** The 
22bc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22bd0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22be0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
22bf0 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  a .** [prepared 
22c00 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74  statement]. If t
22c10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
22c20 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63  .** executed suc
22c30 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f  cessfully, or no
22c40 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
22c50 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f  l, then SQLITE_O
22c60 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  K is returned..*
22c70 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  * If execution o
22c80 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
22c90 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a  failed then an .
22ca0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
22cb0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
22cc0 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
22cd0 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  eturned. .**.** 
22ce0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
22cf0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
22d00 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
22d10 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
22d20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22d30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66   statement].  If
22d40 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
22d50 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  hine has not .**
22d60 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
22d70 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
22d80 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
22d90 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
22da0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
22db0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e  n error or an in
22dc0 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b  terrupt.  (See [
22dd0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
22de0 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d  t()].) .** Incom
22df0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
22e00 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
22e10 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
22e20 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a  s cancelled,  .*
22e30 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
22e40 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
22e50 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65  , and the .** [e
22e60 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
22e70 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
22e80 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
22e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
22ea0 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65  .** {F11302} The
22eb0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22ec0 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  ze(S)] interface
22ed0 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a   destroys the.**
22ee0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22ef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22f00 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c   and releases al
22f10 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  l.**          me
22f20 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65  mory and file re
22f30 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20  sources held by 
22f40 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  that object..**.
22f50 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74  ** {F11304} If t
22f60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
22f70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22f80 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
22f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22fb0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20  ] S returned an 
22fc0 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
22fd0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
22fe0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65  _finalize(S)] re
22ff0 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20  turns that same 
23000 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
23010 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
23020 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
23030 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
23040 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
23050 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
23060 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d   Object {F13330}
23070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23080 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
23090 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
230a0 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72   reset a .** [pr
230b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
230c0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63  ] object..** bac
230d0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
230e0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
230f0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
23100 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
23110 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
23120 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
23130 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
23140 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
23150 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
23160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
23170 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
23180 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
23190 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
231a0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
231b0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
231c0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  gs..**.** {F1133
231d0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
231e0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
231f0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
23200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23210 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
23220 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
23230 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
23240 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rogram..**.** {F
23250 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
23260 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
23270 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
23280 53 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20  S)] for .**     
23290 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
232a0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
232b0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
232c0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
232d0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
232e0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
232f0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
23300 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
23310 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
23320 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
23330 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
23340 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
23350 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  K]..**.** {F1133
23360 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
23370 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
23380 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
23390 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
233a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
233b0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
233c0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
233d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
233e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
233f0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
23400 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
23410 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  e]..**.** {F1133
23420 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
23430 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
23440 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
23450 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
23460 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
23470 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
23480 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
23490 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
234a0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
234b0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
234c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
234d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
234e0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
234f0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
23500 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a  ctions {F16100}.
23510 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
23520 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
23530 72 6f 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a  routines} .**.**
23540 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
23550 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
23560 6c 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22  ly known as.** "
23570 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
23580 6e 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65  n routines") are
23590 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
235a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
235b0 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74  gregates.** or t
235c0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
235d0 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74  ehavior of exist
235e0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
235f0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
23600 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65    The.** differe
23610 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e  nce only between
23620 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74   the two is that
23630 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
23640 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61  meter, the.** na
23650 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
23660 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  r) function or a
23670 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
23680 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
23690 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
236a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
236b0 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71  nd UTF-16 for sq
236c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
236d0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
236e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
236f0 65 6e 74 20 69 73 20 74 68 65 20 5b 64 61 74 61  ent is the [data
23700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23710 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a   that holds the.
23720 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
23730 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20  or aggregate is 
23740 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72  to be added or r
23750 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73  edefined. If a s
23760 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  ingle.** program
23770 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
23780 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  one database han
23790 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  dle internally, 
237a0 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
237b0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
237c0 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  tes must be adde
237d0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
237e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  o each database.
237f0 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  ** handle with w
23800 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
23810 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
23820 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
23830 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
23840 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
23850 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
23860 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
23870 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
23880 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
23890 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
238a0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
238b0 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
238c0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
238d0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
238e0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
238f0 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
23900 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
23910 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
23920 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
23930 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
23940 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
23950 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
23960 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
23970 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
23980 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
23990 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
239a0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
239b0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
239c0 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
239d0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
239e0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
239f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
23a00 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
23a10 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
23a20 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
23a30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
23a40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
23a50 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
23a60 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
23a70 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
23a80 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
23a90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
23aa0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
23ab0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
23ac0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
23ad0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
23ae0 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
23af0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
23b00 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
23b10 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
23b20 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
23b30 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
23b40 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
23b50 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
23b60 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
23b70 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
23b80 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
23b90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23ba0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
23bb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
23bc0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
23bd0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
23be0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
23bf0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
23c00 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
23c10 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
23c20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
23c30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
23c40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
23c50 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
23c60 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
23c70 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
23c80 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
23c90 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
23ca0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
23cb0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
23cc0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
23cd0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
23ce0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
23cf0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
23d00 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
23d10 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
23d20 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
23d30 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
23d40 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
23d50 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
23d60 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
23d70 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
23d80 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
23d90 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
23da0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
23db0 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
23dc0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
23dd0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
23de0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
23df0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
23e00 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
23e10 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
23e20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
23e30 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
23e40 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
23e50 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
23e60 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
23e70 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
23e80 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
23e90 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
23ea0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
23eb0 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
23ec0 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
23ed0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
23ee0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
23ef0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
23f00 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
23f10 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
23f20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
23f30 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
23f40 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
23f50 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
23f60 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
23f70 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
23f80 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
23f90 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
23fa0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
23fb0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
23fc0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
23fd0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
23fe0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
23ff0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
24000 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
24010 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
24020 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
24030 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
24040 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
24050 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
24060 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
24070 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
24080 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
24090 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
240a0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
240b0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
240c0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
240d0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
240e0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
240f0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
24100 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
24110 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24120 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65  .** {F16103} The
24130 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24140 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
24150 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
24160 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
24170 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
24180 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24190 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
241a0 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
241b0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
241c0 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
241d0 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
241e0 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  ent as.**       
241f0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
24200 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
24210 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
24220 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20  ead of as a.**  
24230 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
24240 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
24250 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 0a 2a  *.** {F16106} .*
24260 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
24270 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
24280 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
24290 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
242a0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
242b0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
242c0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
242d0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
242e0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
242f0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24300 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
24310 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
24320 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
24330 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
24340 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
24350 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
24360 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
24370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24380 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
24390 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
243a0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
243b0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
243c0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
243d0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
243e0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
243f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
24400 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
24410 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
24420 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
24430 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24440 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
24450 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
24460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
24470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24480 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
24490 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a  s {F10267}.**.**
244a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
244b0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
244c0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
244d0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
244e0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
244f0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
24500 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
24510 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
24520 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
24530 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
24540 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
24550 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
24560 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
24570 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
24580 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
24590 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
245a0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
245b0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
245c0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
245d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
245e0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
245f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24600 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
24610 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
24620 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
24630 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
24640 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
24650 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
24660 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
24670 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
24680 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
24690 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
246a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
246b0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
246c0 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
246d0 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
246e0 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
246f0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
24700 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
24710 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
24720 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
24730 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
24740 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
24750 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
24760 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
24770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
24780 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
24790 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
247a0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
247b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
247c0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
247d0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
247e0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
247f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
24800 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
24810 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
24820 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
24830 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
24840 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
24850 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
24860 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
24870 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
24880 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  ;.int sqlite3_me
24890 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
248a0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
248b0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
248c0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
248d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
248e0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
248f0 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
24900 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31  ter Values {F151
24910 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00}.**.** The C-
24920 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
24930 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
24940 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
24950 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
24960 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
24970 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
24980 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
24990 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
249a0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
249b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
249c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
249d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
249e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
249f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
24a00 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
24a10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24a20 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
24a30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24a40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
24a50 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
24a60 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
24a70 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
24a80 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
24a90 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
24aa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
24ab0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
24ac0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
24ad0 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ers to.** [sqlit
24ae0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
24af0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
24b00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
24b10 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
24b20 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
24b30 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24b40 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
24b50 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
24b60 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
24b70 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
24b80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
24b90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
24ba0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
24bb0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
24bc0 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71  sponding .** [sq
24bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
24be0 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  b | sqlite3_colu
24bf0 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65  mn_* routines] e
24c00 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74  xcept that .** t
24c10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
24c20 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c  ke a single [sql
24c30 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69  ite3_value*] poi
24c40 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  nter instead.** 
24c50 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73  of an [sqlite3_s
24c60 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
24c70 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
24c80 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
24c90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
24ca0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
24cb0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
24cc0 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a  a UTF16 string.*
24cd0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
24ce0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
24cf0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
24d00 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
24d10 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
24d20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
24d30 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
24d40 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
24d50 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67  act UTF16 string
24d60 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
24d70 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
24d80 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
24d90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24da0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
24db0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
24dc0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
24dd0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
24de0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
24df0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
24e00 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
24e10 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
24e20 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
24e30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
24e40 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
24e50 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
24e60 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
24e70 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
24e80 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
24e90 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
24ea0 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c  words if the val
24eb0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
24ec0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
24ed0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
24ee0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
24ef0 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77  is done.  Otherw
24f00 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
24f10 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a  n occurs.  The .
24f20 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
24f30 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
24f40 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
24f50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
24f60 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
24f70 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
24f80 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
24f90 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
24fa0 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72  that.** is retur
24fb0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
24fc0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
24fd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
24fe0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
24ff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25000 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
25010 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
25020 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
25030 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
25040 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
25050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
25060 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
25070 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
25080 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
25090 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
250a0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .  .**.** These 
250b0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
250c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
250d0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
250e0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
250f0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
25100 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  d the sqlite3_va
25110 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  lue* parameters.
25120 0a 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65 20 73  .** Or, if the s
25130 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 61 72  qlite3_value* ar
25140 67 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  gument comes fro
25150 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
25160 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a  olumn_value()].*
25170 2a 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  * interface, the
25180 6e 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  n these routines
25190 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
251a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
251b0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 74 20 72  thread.** that r
251c0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  an [sqlite3_colu
251d0 6d 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 0a  mn_value()]..**.
251e0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
251f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
25200 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
25210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
25220 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
25230 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
25240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
25250 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
25260 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
25270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
25280 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
25290 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
252a0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
252b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
252c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
252d0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
252e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
252f0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
25300 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
25310 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
25320 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
25330 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
25340 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25350 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
25360 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
25370 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
25380 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
25390 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
253a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
253b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
253c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
253d0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
253e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
253f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
25400 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
25410 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
25420 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
25430 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
25440 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36  ion Context {F16
25450 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  210}.**.** The i
25460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
25470 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25480 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
25490 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
254a0 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
254b0 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
254c0 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a   their state.  .
254d0 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20  ** {F16211} The 
254e0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
254f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
25500 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
25510 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c  ne is.** is call
25520 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ed for a particu
25530 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
25540 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
25550 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
25560 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d  .** zeros that m
25570 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
25580 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
25590 69 74 2e 0a 2a 2a 20 7b 46 31 36 32 31 32 7d 20  it..** {F16212} 
255a0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
255b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
255c0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
255d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 0a 2a 2a  ate_context().**
255e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
255f0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
25600 20 69 6e 64 65 78 2c 20 74 68 65 20 73 61 6d 65   index, the same
25610 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
25620 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68  ned. {END}.** Th
25630 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25640 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65  .** of the aggre
25650 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65  gate can use the
25660 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72   returned buffer
25670 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64   to accumulate d
25680 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ata..**.** {F162
25690 31 33 7d 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  13} SQLite autom
256a0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
256b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
256c0 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
256d0 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
256e0 63 6f 6e 63 6c 75 64 65 73 2e 20 7b 45 4e 44 7d  concludes. {END}
256f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25700 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
25710 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
25720 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
25730 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
25740 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
25750 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
25760 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
25770 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
25780 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
25790 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
257a0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
257b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
257c0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
257d0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
257e0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
257f0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
25800 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
25810 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
25820 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
25830 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
25840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
25850 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
25860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
25870 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
25880 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a  ctions {F16240}.
25890 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 31 7d 20 54  **.** {F16241} T
258a0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
258b0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
258c0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
258d0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
258e0 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
258f0 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
25900 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
25910 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
25920 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
25930 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
25940 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
25950 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25960 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
25970 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
25980 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
25990 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
259a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
259b0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 32  END}.**.** {U162
259c0 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
259d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
259e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
259f0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
25a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25a10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25a20 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
25a30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
25a40 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
25a50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
25a60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
25a70 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
25a80 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a  Data {F16270}.**
25a90 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
25aa0 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
25ab0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
25ac0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
25ad0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
25ae0 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69  ate meta-data wi
25af0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
25b00 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
25b10 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
25b20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
25b30 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
25b40 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
25b50 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
25b60 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
25b70 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
25b80 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
25b90 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61  ciated meta-data
25ba0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
25bb0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
25bc0 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
25bd0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
25be0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
25bf0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
25c00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
25c10 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
25c20 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
25c30 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
25c40 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
25c50 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  a-data associate
25c60 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
25c70 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
25c80 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
25c90 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
25ca0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
25cb0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
25cc0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
25cd0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
25ce0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
25cf0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
25d00 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
25d10 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
25d20 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
25d30 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
25d40 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
25d50 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
25d60 20 7b 46 31 36 32 37 31 7d 0a 2a 2a 20 54 68 65   {F16271}.** The
25d70 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
25d80 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
25d90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
25da0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64  er to the meta-d
25db0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
25dc0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
25dd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
25de0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
25df0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
25e00 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
25e10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25e20 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b  d function..** {
25e30 46 31 36 32 37 32 7d 20 49 66 20 6e 6f 20 6d 65  F16272} If no me
25e40 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e  ta-data has been
25e50 20 65 76 65 72 20 62 65 65 6e 20 73 65 74 20 66   ever been set f
25e60 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72  or the Nth.** ar
25e70 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
25e80 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
25e90 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69 6e 67 20  e cooresponding 
25ea0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
25eb0 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65  er.** has change
25ec0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
25ed0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 20 74  -data was set, t
25ee0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
25ef0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74  auxdata().** ret
25f00 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
25f10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ter..**.** {F162
25f20 37 35 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  75} The sqlite3_
25f30 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
25f40 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
25f50 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70  e meta-data.** p
25f60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
25f70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
25f80 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  s the meta-data 
25f90 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
25fa0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
25fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
25fd0 4e 44 7d 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  ND} Subsequent.*
25fe0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
25ff0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
26000 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
26010 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
26020 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
26030 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 7b 46  estroyed. .** {F
26040 31 36 32 37 37 7d 20 49 66 20 69 74 20 69 73 20  16277} If it is 
26050 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
26060 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
26070 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a 2a 20   destructor .** 
26080 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
26090 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
260a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
260b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
260c0 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ** the meta-data
260d0 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
260e0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
260f0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
26100 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
26110 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
26120 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
26130 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
26140 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 6e  . {END}.**.** In
26150 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
26160 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
26170 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
26180 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
26190 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
261a0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
261b0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
261c0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
261d0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
261e0 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
261f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
26200 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
26210 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
26220 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
26230 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
26240 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
26250 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
26260 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
26270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26280 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
26290 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
262a0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
262b0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
262c0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
262d0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
262e0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
262f0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
26300 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
26310 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a  havior {F10280}.
26320 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
26330 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f  special value fo
26340 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
26350 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
26360 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
26370 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
26380 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
26390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
263a0 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
263b0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
263c0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
263d0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
263e0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
263f0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
26400 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
26410 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
26420 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
26430 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
26440 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54  .  The .** SQLIT
26450 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
26460 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
26470 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
26480 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
26490 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
264a0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
264b0 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
264c0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
264d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
264e0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
264f0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
26500 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
26510 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
26520 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
26530 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
26540 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
26550 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
26560 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
26570 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
26580 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
26590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
265a0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
265b0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
265c0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
265d0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
265e0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
265f0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
26600 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
26610 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
26620 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
26630 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30  Function {F16400
26640 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
26650 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
26660 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
26670 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
26680 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
26690 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
266a0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
266b0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
266c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
266d0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
266e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
266f0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
26700 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
26710 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
26720 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
26730 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
26740 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
26750 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
26760 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d  ite3_bind_*] fam
26770 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
26780 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64   used.** to bind
26790 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
267a0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
267b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
267c0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
267d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
267e0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
267f0 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65  e3_bind_* docume
26800 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20  ntation] for.** 
26810 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26820 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  mation..**.** {F
26830 31 36 34 30 32 7d 20 54 68 65 20 73 71 6c 69 74  16402} The sqlit
26840 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
26850 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
26860 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
26870 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
26880 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
26890 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
268a0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
268b0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
268c0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
268d0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
268e0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
268f0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
26900 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
26910 65 74 65 72 2e 20 0a 2a 2a 20 7b 46 31 36 34 30  eter. .** {F1640
26920 33 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  3} The sqlite3_r
26930 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
26940 20 69 6e 65 72 66 61 63 65 73 20 73 65 74 20 74   inerfaces set t
26950 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
26960 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26970 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26980 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
26990 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
269a0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
269b0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
269c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
269d0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
269e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
269f0 20 7b 46 31 36 34 30 37 7d 20 54 68 65 20 73 71   {F16407} The sq
26a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
26a10 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
26a20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
26a30 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
26a40 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
26a50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
26a60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
26a70 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
26a80 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
26a90 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ument..**.** {F1
26aa0 36 34 30 39 7d 20 54 68 65 20 73 71 6c 69 74 65  6409} The sqlite
26ab0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
26ac0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
26ad0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
26ae0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
26af0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
26b00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
26b10 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
26b20 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 34 31 31 7d  ion..** {F16411}
26b30 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
26b40 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
26b50 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
26b60 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
26b70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
26b80 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
26b90 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
26ba0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
26bb0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
26bc0 61 67 65 2e 20 7b 46 31 36 34 31 32 7d 20 53 51  age. {F16412} SQ
26bd0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
26be0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
26bf0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
26c00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
26c10 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e  error() as UTF8.
26c20 20 20 7b 46 31 36 34 31 33 7d 20 53 51 4c 69 74    {F16413} SQLit
26c30 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
26c40 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
26c50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
26c60 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31  rror16() as UTF1
26c70 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
26c80 79 74 65 20 6f 72 64 65 72 2e 20 20 7b 46 31 36  yte order.  {F16
26c90 34 31 34 7d 20 49 66 20 74 68 65 20 74 68 69 72  414} If the thir
26ca0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
26cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26cc0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
26cd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26ce0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
26cf0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
26d00 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
26d10 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
26d20 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
26d30 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
26d40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46 31 36  aracter..** {F16
26d50 34 31 35 7d 20 49 66 20 74 68 65 20 74 68 69 72  415} If the thir
26d60 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
26d70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
26d80 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
26d90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
26da0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
26db0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
26dc0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
26dd0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
26de0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
26df0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
26e00 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
26e10 65 73 73 61 67 65 2e 0a 2a 2a 20 7b 46 31 36 34  essage..** {F164
26e20 31 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  17} The sqlite3_
26e30 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
26e40 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
26e50 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
26e60 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63  outines make a c
26e70 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79  opy private copy
26e80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
26e90 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
26ea0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
26eb0 2e 20 20 7b 45 4e 44 7d 20 48 65 6e 63 65 2c 20  .  {END} Hence, 
26ec0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
26ed0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
26ee0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
26ef0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
26f00 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
26f10 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20  out harm..**.** 
26f20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 73 71 6c  {F16421} The sql
26f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
26f40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
26f50 61 75 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a 20  auses SQLite.** 
26f60 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
26f70 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
26f80 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
26f90 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a  OB is to long.**
26fa0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 20 20   to represent.  
26fb0 7b 46 31 36 34 32 32 7d 20 54 68 65 20 73 71 6c  {F16422} The sql
26fc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
26fd0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  m() interface.**
26fe0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
26ff0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
27000 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20  tion indicating 
27010 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65  that the a.** me
27020 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
27030 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  failed..**.** {F
27040 31 36 34 33 31 7d 20 54 68 65 20 73 71 6c 69 74  16431} The sqlit
27050 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
27060 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
27070 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
27080 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
27090 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
270a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
270b0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
270c0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
270d0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
270e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 7b 46   argument..** {F
270f0 31 36 34 33 32 7d 20 54 68 65 20 73 71 6c 69 74  16432} The sqlit
27100 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
27110 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
27120 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
27130 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
27140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27150 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
27160 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
27170 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
27180 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
27190 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
271a0 2a 2a 20 7b 46 31 36 34 33 37 7d 20 54 68 65 20  ** {F16437} The 
271b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
271c0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
271d0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
271e0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
271f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27200 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
27210 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  be NULL..**.** {
27220 46 31 36 34 34 31 7d 20 54 68 65 20 73 71 6c 69  F16441} The sqli
27230 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
27240 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
27250 74 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20  t_text16(), .** 
27260 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27270 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
27280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27290 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
272a0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
272b0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
272c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
272d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
272e0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
272f0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
27300 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
27310 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
27320 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
27330 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
27340 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
27350 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
27360 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27370 7b 46 31 36 34 34 32 7d 20 53 51 4c 69 74 65 20  {F16442} SQLite 
27380 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
27390 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
273a0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
273b0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
273c0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
273d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
273e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
273f0 7b 46 31 36 34 34 34 7d 20 49 66 20 74 68 65 20  {F16444} If the 
27400 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
27410 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
27420 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
27430 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
27440 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
27450 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
27460 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
27470 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68  parameter .** th
27480 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
27490 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
274a0 2a 2a 20 7b 46 31 36 34 34 37 7d 20 49 66 20 74  ** {F16447} If t
274b0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
274c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
274d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
274e0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
274f0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
27500 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
27510 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
27520 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
27530 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
27540 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
27550 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
27560 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27570 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
27580 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34  result..** {F164
27590 35 31 7d 20 49 66 20 74 68 65 20 34 74 68 20 70  51} If the 4th p
275a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
275b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
275c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
275d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
275e0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
275f0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
27600 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
27610 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
27620 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
27630 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
27640 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74  t or blob result
27650 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
27660 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
27670 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b  hat result..** {
27680 46 31 36 34 35 33 7d 20 49 66 20 74 68 65 20 34  F16453} If the 4
27690 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
276a0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
276b0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
276c0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
276d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
276e0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
276f0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
27700 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  TIC, then.** SQL
27710 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
27720 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f   the text or blo
27730 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73  b result is cons
27740 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a 2a  tant space and.*
27750 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20  * does not copy 
27760 74 68 65 20 73 70 61 63 65 20 6f 72 20 63 61 6c  the space or cal
27770 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
27780 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
27790 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
277a0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31  t result..** {F1
277b0 36 34 35 34 7d 20 49 66 20 74 68 65 20 34 74 68  6454} If the 4th
277c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
277d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
277e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
277f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
27800 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
27810 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
27820 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
27830 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
27840 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
27850 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
27860 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
27870 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
27880 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
27890 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
278a0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  urns..**.** {F16
278b0 34 36 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  461} The sqlite3
278c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
278d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
278e0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
278f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
27900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27910 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
27920 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27930 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 73 70 65 63  ].** object spec
27940 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
27950 20 70 61 72 61 6d 65 74 65 72 2e 20 20 7b 46 31   parameter.  {F1
27960 36 34 36 33 7d 20 54 68 65 0a 2a 2a 20 73 71 6c  6463} The.** sql
27970 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
27980 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
27990 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
279a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
279b0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71  ].** so that [sq
279c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
279d0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
279e0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
279f0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
27a00 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
27a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
27a20 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
27a30 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a  hout harm..**.**
27a40 20 7b 55 31 36 34 39 31 7d 20 54 68 65 73 65 20   {U16491} These 
27a50 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
27a60 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
27a70 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
27a80 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68  read .** than th
27a90 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
27aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27ab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
27ac0 6e 20 74 68 61 74 20 72 65 63 69 65 76 65 64 0a  n that recieved.
27ad0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
27ae0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
27af0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
27b00 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
27b10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27b20 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
27b30 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27b40 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
27b50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
27b60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27b70 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
27b80 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
27b90 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
27ba0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
27bb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27bc0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
27bd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27be0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
27bf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27c00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
27c10 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
27c20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
27c30 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
27c40 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
27c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27c60 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
27c70 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
27c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27c90 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
27ca0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
27cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27cc0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
27cd0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
27ce0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
27cf0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
27d00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27d10 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27d20 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
27d30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27d40 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
27d50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27d60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27d70 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
27d80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
27d90 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
27da0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
27db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
27dc0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
27dd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27de0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
27df0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
27e00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27e10 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
27e20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
27e30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
27e40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
27e50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
27e60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
27e70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
27e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27e90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
27ea0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
27eb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
27ec0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
27ed0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
27ee0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
27ef0 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a  uences {F16600}.
27f00 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 31 7d 0a 2a  **.** {F16601}.*
27f10 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
27f20 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
27f30 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
27f40 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
27f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  .** [sqlite3*] h
27f60 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
27f70 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
27f80 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  ument. .**.** {F
27f90 31 36 36 30 32 7d 0a 2a 2a 20 54 68 65 20 6e 61  16602}.** The na
27fa0 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
27fb0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
27fc0 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
27fd0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
27fe0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
27ff0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28000 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
28010 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
28020 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
28030 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
28040 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28050 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 7b 46 31  llation16(). {F1
28060 36 36 30 33 7d 20 49 6e 20 61 6c 6c 20 63 61 73  6603} In all cas
28070 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
28080 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
28090 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
280a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
280b0 7b 46 31 36 36 30 34 7d 0a 2a 2a 20 54 68 65 20  {F16604}.** The 
280c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
280d0 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
280e0 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
280f0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
28100 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72  LITE_UTF16LE] or
28110 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
28120 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
28130 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
28140 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
28150 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
28160 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
28170 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
28180 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
28190 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
281a0 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20  ndian or UTF-16 
281b0 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  big-endian respe
281c0 63 74 69 76 65 6c 79 2e 20 7b 46 31 36 36 30 35  ctively. {F16605
281d0 7d 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  } The.** third a
281e0 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
281f0 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
28200 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20  F16_ALIGNED] to 
28210 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a  indicate that.**
28220 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70   the routine exp
28230 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
28240 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69   16-bit word ali
28250 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  gned strings.** 
28260 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68 65 20  of UTF16 in the 
28270 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
28280 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f  r of the host co
28290 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  mputer..**.** {F
282a0 31 36 36 30 37 7d 0a 2a 2a 20 41 20 70 6f 69 6e  16607}.** A poin
282b0 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
282c0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
282d0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
282e0 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
282f0 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 36 36 30  argument. {F1660
28300 39 7d 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  9} If it is NULL
28310 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
28320 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
28330 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
28340 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
28350 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
28360 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
28370 2e 0a 2a 2a 20 7b 46 31 36 36 31 31 7d 20 45 61  ..** {F16611} Ea
28380 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
28390 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  ication.** suppl
283a0 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
283b0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
283c0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
283d0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64  the void* passed
283e0 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74   as.** the fourt
283f0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
28400 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28410 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73  lation() or.** s
28420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28430 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69  llation16() as i
28440 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
28450 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  er..**.** {F1661
28460 32 7d 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  2}.** The remain
28470 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
28480 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28490 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
284a0 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
284b0 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
284c0 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
284d0 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
284e0 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
284f0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
28500 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
28510 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
28520 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
28530 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
28540 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
28550 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70  ed. {END} The ap
28560 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28570 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
28580 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
28590 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
285a0 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
285b0 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  if.** the first 
285c0 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
285d0 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
285e0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
285f0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72  he second.** str
28600 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
28610 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
28620 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 0a 2a 2a  *.** {F16615}.**
28630 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
28640 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
28650 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
28660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
28670 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61  lation().** exca
28680 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
28690 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
286a0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
286b0 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
286c0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
286d0 7b 46 31 36 36 31 37 7d 20 54 68 65 20 64 65 73  {F16617} The des
286e0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
286f0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
28700 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
28710 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
28720 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
28730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28740 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
28750 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
28760 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28770 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 7b 46 31 36  on_v2()..** {F16
28780 36 31 38 7d 20 20 43 6f 6c 6c 61 74 69 6f 6e 73  618}  Collations
28790 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
287a0 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  hen.** they are 
287b0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
287c0 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
287d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
287e0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ion functions.**
287f0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71   or when the [sq
28800 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65  lite3*] database
28810 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65   handle is close
28820 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
28830 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _close()]..*/.in
28840 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
28850 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
28860 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
28870 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
28880 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
28890 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
288a0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
288b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
288c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
288d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
288e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
288f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
28900 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
28910 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
28920 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
28930 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
28940 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
28950 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
28960 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
28970 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
28980 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
28990 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
289a0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
289b0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
289c0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
289d0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
289e0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
289f0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
28a00 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
28a10 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
28a20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28a30 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
28a40 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37   Callbacks {F167
28a50 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30  00}.**.** {F1670
28a60 31 7d 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68  1}.** To avoid h
28a70 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
28a80 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
28a90 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
28aa0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
28ab0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
28ac0 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
28ad0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
28ae0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
28af0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61  e.** database ha
28b00 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65  ndle to be calle
28b10 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
28b20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
28b30 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a  n sequence is.**
28b40 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
28b50 20 7b 46 31 36 37 30 32 7d 0a 2a 2a 20 49 66 20   {F16702}.** If 
28b60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
28b70 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
28b80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
28b90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28ba0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
28bb0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
28bc0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
28bd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
28be0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
28bf0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
28c00 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66  F-8. {F16703} If
28c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
28c20 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
28c30 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73   used, the names
28c40 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61  .** are passed a
28c50 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
28c60 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
28c70 6f 72 64 65 72 2e 20 7b 46 31 36 37 30 34 7d 20  order. {F16704} 
28c80 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
28c90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  .** function rep
28ca0 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69  laces any existi
28cb0 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ng callback..**.
28cc0 2a 2a 20 7b 46 31 36 37 30 35 7d 20 57 68 65 6e  ** {F16705} When
28cd0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
28ce0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
28cf0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
28d00 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
28d10 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
28d20 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
28d30 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28d40 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
28d50 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
28d60 65 64 65 64 31 36 28 29 2e 20 7b 46 31 36 37 30  eded16(). {F1670
28d70 36 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  6} The second ar
28d80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
28d90 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65  tabase.** handle
28da0 2e 20 20 7b 46 31 36 37 30 37 7d 20 54 68 65 20  .  {F16707} The 
28db0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
28dc0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
28dd0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
28de0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
28df0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
28e00 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
28e10 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62   most.** desirab
28e20 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
28e30 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
28e40 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
28e50 72 65 64 2e 0a 2a 2a 20 7b 46 31 36 37 30 38 7d  red..** {F16708}
28e60 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
28e70 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
28e80 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
28e90 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
28ea0 65 71 75 65 6e 63 65 2e 20 7b 45 4e 44 7d 0a 2a  equence. {END}.*
28eb0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
28ec0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
28ed0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
28ee0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
28ef0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
28f00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28f10 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
28f20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28f30 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
28f40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28f50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
28f60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
28f70 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
28f80 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
28f90 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
28fa0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
28fb0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
28fc0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
28fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
28fe0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
28ff0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
29000 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
29010 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
29020 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
29030 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
29040 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
29050 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
29060 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
29070 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
29080 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
29090 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
290a0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
290b0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
290c0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
290d0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
290e0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
290f0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
29100 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
29110 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
29120 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
29130 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
29140 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
29150 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
29160 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
29170 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
29180 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
29190 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
291a0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
291b0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
291c0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
291d0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
291e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
291f0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
29200 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
29210 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
29220 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
29230 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
29240 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
29250 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
29260 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
29270 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
29280 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
29290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
292a0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
292b0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
292c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
292d0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
292e0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
292f0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
29300 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
29310 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
29320 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
29330 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
29340 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31  A Short Time {F1
29350 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  0530}.**.** {F10
29360 35 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  531} The sqlite3
29370 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
29380 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20  n.** causes the 
29390 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
293a0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
293b0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
293c0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
293d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
293e0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
293f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
29400 46 31 30 35 33 32 7d 20 49 66 20 74 68 65 20 6f  F10532} If the o
29410 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
29420 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
29430 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
29440 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65  with .** millise
29450 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
29460 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
29470 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
29480 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68  ded up to .** th
29490 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
294a0 2e 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20 6e  . {F10533} The n
294b0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
294c0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
294d0 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75  ctually .** requ
294e0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
294f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
29500 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
29510 2a 2a 20 7b 46 31 30 35 33 34 7d 20 53 51 4c 69  ** {F10534} SQLi
29520 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
29530 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
29540 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
29550 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
29560 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
29570 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
29580 63 74 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  ct. {END}.*/.int
29590 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
295a0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
295b0 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54  3REF:  Name Of T
295c0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
295d0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
295e0 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a  s {F10310}.**.**
295f0 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
29600 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
29610 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
29620 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
29630 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
29640 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69  folder (a.ka. di
29650 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
29660 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
29670 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
29680 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
29690 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
296a0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
296b0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
296c0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  s NULL pointer, 
296d0 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73  then SQLite does
296e0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
296f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d   appropriate tem
29700 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64  porary.** file d
29710 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
29720 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
29730 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
29740 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61  riable once a da
29750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29760 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70  n.** has been op
29770 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74  ened.  It is int
29780 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
29790 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
297a0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
297b0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
297c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
297d0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
297e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
297f0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
29800 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20  call and remain 
29810 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61  unchanged therea
29820 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  fter..*/.SQLITE_
29830 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
29840 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
29850 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
29860 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53  3REF:  Test To S
29870 65 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61  ee If The Databa
29880 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f  se Is In Auto-Co
29890 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33  mmit Mode {F1293
298a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
298b0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
298c0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 73  mit() interfaces
298d0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
298e0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
298f0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
29900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
29910 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
29920 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
29930 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
29940 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
29950 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65  e is on.** by de
29960 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d  fault.  Autocomm
29970 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
29980 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
29990 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41   statement..** A
299a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
299b0 73 20 72 65 65 6e 61 62 6c 65 64 20 62 79 20 61  s reenabled by a
299c0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
299d0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
299e0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
299f0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
29a00 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
29a10 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
29a20 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
29a30 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20  actions (errors 
29a40 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
29a50 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
29a60 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51  _IOERR], .** [SQ
29a70 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
29a80 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
29a90 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
29aa0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
29ab0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
29ac0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
29ad0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
29ae0 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
29af0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20  .** find out if 
29b00 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
29b10 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
29b20 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
29b30 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
29b40 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
29b50 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
29b60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29b70 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65  .** {F12931} The
29b80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
29b90 74 6f 63 6f 6d 6d 69 74 28 29 5d 20 69 6e 74 65  tocommit()] inte
29ba0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
29bb0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20  n-zero or.**    
29bc0 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68        zero if th
29bd0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
29be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
29bf0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
29c00 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20  commit.**       
29c10 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74     mode, respect
29c20 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ively..**.** {F1
29c30 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2932} Autocommit
29c40 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
29c50 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  efault..**.** {F
29c60 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69  12933} Autocommi
29c70 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
29c80 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
29c90 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65  ul [BEGIN] state
29ca0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ment..**.** {F12
29cb0 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  934} Autocommit 
29cc0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
29cd0 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
29ce0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
29cf0 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20  LBACK].**       
29d00 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a     statement..**
29d10 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49   .**.** LIMITATI
29d20 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32  ONS:.***.** {U12
29d30 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  936} If another 
29d40 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
29d50 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
29d60 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
29d70 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
29d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
29d90 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
29da0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
29db0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
29dd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
29de0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
29df0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
29e00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29e10 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44  REF:  Find The D
29e20 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
29e30 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
29e40 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a  tement {F13120}.
29e50 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 31 7d 20 54  **.** {F13121} T
29e60 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
29e70 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  ndle interface.*
29e80 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73  * returns the [s
29e90 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
29ea0 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63  e handle to whic
29eb0 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  h a.** [prepared
29ec0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
29ed0 6e 67 73 2e 0a 2a 2a 20 7b 46 31 33 31 32 32 7d  ngs..** {F13122}
29ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
29ef0 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
29f00 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
29f10 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61 6d  le.** is the sam
29f20 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
29f30 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68  e that was.** th
29f40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29f50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
29f60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
29f70 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  r its variants.*
29f80 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  * that was used 
29f90 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74  to create the st
29fa0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
29fb0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
29fc0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
29fd0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
29fe0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a  3_stmt*);.../*.*
29ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
2a000 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
2a010 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2a020 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a  lbacks {F12950}.
2a030 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54  **.** {F12951} T
2a040 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2a050 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
2a060 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2a070 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2a080 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2a090 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2a0a0 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
2a0b0 69 74 74 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 35  itted..** {F1295
2a0c0 32 7d 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  2} Any callback 
2a0d0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2a0e0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2a0f0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2a100 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2a110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a120 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2a130 6e 2e 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 54  n..** {F12953} T
2a140 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2a150 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2a160 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2a170 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2a180 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2a190 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2a1a0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
2a1b0 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 7b 46 31 32  mmitted..** {F12
2a1c0 39 35 34 7d 20 41 6e 79 20 63 61 6c 6c 62 61 63  954} Any callbac
2a1d0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2a1e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2a1f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2a200 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2a210 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2a220 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2a230 64 65 6e 2e 0a 2a 2a 20 7b 46 31 32 39 35 36 7d  den..** {F12956}
2a240 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
2a250 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
2a260 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ough.** to the c
2a270 61 6c 6c 62 61 63 6b 2e 20 20 7b 46 31 32 39 35  allback.  {F1295
2a280 37 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  7} If the callba
2a290 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
2a2a0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  ook function .**
2a2b0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2a2c0 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  o, then the comm
2a2d0 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
2a2e0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
2a2f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 38 7d 20  .**.** {F12958} 
2a300 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2a310 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2a320 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2a330 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
2a340 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2a350 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2a360 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2a370 20 7b 46 31 32 39 35 39 7d 20 52 65 67 69 73 74   {F12959} Regist
2a380 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
2a390 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
2a3a0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2a3b0 2a 2a 20 7b 46 31 32 39 36 31 7d 20 46 6f 72 20  ** {F12961} For 
2a3c0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2a3d0 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2a3e0 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2a3f0 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a  to have been .**
2a400 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2a410 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2a420 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2a430 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2a440 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2a450 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
2a460 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
2a470 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
2a480 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68 65  .** {F12962} The
2a490 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2a4a0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2a4b0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2a4c0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2a4d0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2a4e0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2a4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a500 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2a510 20 7b 46 31 32 39 36 34 7d 20 54 68 65 20 72 6f   {F12964} The ro
2a520 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2a530 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2a540 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2a550 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
2a560 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
2a570 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
2a580 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
2a590 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f  * <todo> Check o
2a5a0 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 20 7b  n this </todo> {
2a5b0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
2a5c0 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61   are experimenta
2a5d0 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64  l interfaces and
2a5e0 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
2a5f0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20  change..*/.void 
2a600 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2a610 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2a620 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2a630 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2a640 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2a650 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2a660 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2a670 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2a680 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2a690 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2a6a0 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30  allbacks {F12970
2a6b0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d  }.**.** {F12971}
2a6c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
2a6d0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
2a6e0 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65 72  face.** register
2a6f0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
2a700 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64  ction with the d
2a710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a720 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  on identified by
2a730 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61   the .** first a
2a740 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e  rgument to be in
2a750 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2a760 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2a770 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2a780 65 74 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 37 32  eted..** {F12972
2a790 7d 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  } Any callback s
2a7a0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2a7b0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2a7c0 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
2a7d0 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
2a7e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2a7f0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2a800 20 7b 46 31 32 39 37 34 7d 20 54 68 65 20 73 65   {F12974} The se
2a810 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2a820 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2a830 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
2a840 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20  voke when a .** 
2a850 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
2a860 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
2a870 74 65 64 2e 20 0a 2a 2a 20 7b 46 31 32 39 37 36  ted. .** {F12976
2a880 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
2a890 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2a8a0 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70  back is.** a cop
2a8b0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2a8c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a8d0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2a8e0 2e 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 54 68  ..** {F12977} Th
2a8f0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
2a900 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
2a910 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2a920 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
2a930 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51  E_DELETE] or [SQ
2a940 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a  LITE_UPDATE],.**
2a950 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2a960 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2a970 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2a980 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
2a990 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 37 38 7d 20  ed..** {F12978} 
2a9a0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a  The third and .*
2a9b0 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
2a9c0 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
2a9d0 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
2a9e0 65 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  ers to the datab
2a9f0 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c  ase and .** tabl
2aa00 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2aa10 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2aa20 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20  ow..** {F12979} 
2aa30 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
2aa40 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
2aa50 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66  .** the rowid of
2aa60 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 7b 46 31   the row..** {F1
2aa70 32 39 38 31 7d 20 49 6e 20 74 68 65 20 63 61 73  2981} In the cas
2aa80 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
2aa90 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
2aaa0 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20  d after .** the 
2aab0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
2aac0 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ce..**.** {F1298
2aad0 33 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  3} The update ho
2aae0 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2aaf0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2ab00 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2ab10 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2ab20 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2ab30 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2ab40 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  uence)..**.** {F
2ab50 31 32 39 38 34 7d 20 49 66 20 61 6e 6f 74 68 65  12984} If anothe
2ab60 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
2ab70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
2ab80 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
2ab90 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72  alue.** is retur
2aba0 6e 65 64 2e 20 20 7b 46 31 32 39 38 35 7d 20 4f  ned.  {F12985} O
2abb0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2abc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76 6f   returned..*/.vo
2abd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
2abe0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
2abf0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
2ac00 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
2ac10 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
2ac20 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
2ac30 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
2ac40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac50 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
2ac60 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
2ac70 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d  r Cache {F10330}
2ac80 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 0a  .**.** {F10331}.
2ac90 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2aca0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2acb0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2acc0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2acd0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2ace0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2acf0 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  res between conn
2ad00 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73  ections to the s
2ad10 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  ame database..**
2ad20 20 7b 46 31 30 33 33 32 7d 0a 2a 2a 20 53 68 61   {F10332}.** Sha
2ad30 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2ad40 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2ad50 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61  is true and disa
2ad60 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2ad70 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65  ment.** is false
2ad80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 33 7d  ..**.** {F10333}
2ad90 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
2ada0 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
2adb0 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
2adc0 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2add0 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61   {END} This is a
2ade0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2adf0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2ae00 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20  .0..** In prior 
2ae10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2ae20 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a  te, sharing was.
2ae30 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
2ae40 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
2ae50 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
2ae60 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 34  y..**.** {F10334
2ae70 7d 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  }.** The cache s
2ae80 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
2ae90 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
2aea0 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
2aeb0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2aec0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
2aed0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2aee0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2aef0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2af00 29 5d 2e 0a 2a 2a 20 7b 46 31 30 33 33 35 7d 20  )]..** {F10335} 
2af10 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
2af20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
2af30 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
2af40 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
2af50 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
2af60 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
2af70 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 20  ey were opened. 
2af80 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74  {END}.**.** Virt
2af90 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
2afa0 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
2afb0 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
2afc0 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68  {F10336} When sh
2afd0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
2afe0 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
2aff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2b000 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64  dule()] API used
2b010 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
2b020 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77  virtual tables w
2b030 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
2b040 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 45 4e 44  n an error. {END
2b050 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d  }.**.** {F10337}
2b060 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
2b070 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2b080 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
2b090 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  e was.** enabled
2b0a0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
2b0b0 63 65 73 73 66 75 6c 6c 79 2e 20 20 7b 46 31 30  cessfully.  {F10
2b0c0 33 33 38 7d 20 41 6e 20 5b 65 72 72 6f 72 20 63  338} An [error c
2b0d0 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
2b0e0 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 20 7b  ned otherwise. {
2b0f0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  END}.**.** {F103
2b100 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68 65  39} Shared cache
2b110 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2b120 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 42  default. {END} B
2b130 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
2b140 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
2b150 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2b160 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
2b170 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
2b180 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
2b190 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
2b1a0 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
2b1b0 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  itly..*/.int sql
2b1c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
2b1d0 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
2b1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b1f0 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2b200 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31   Heap Memory {F1
2b210 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  7340}.**.** {F17
2b220 33 34 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  341} The sqlite3
2b230 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2b240 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2b250 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20  mpts to.** free 
2b260 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
2b270 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
2b280 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
2b290 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tial memory.** a
2b2a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
2b2b0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2b2c0 6c 61 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  labrary. {END}  
2b2d0 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74  Memory used.** t
2b2e0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
2b2f0 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
2b300 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
2b310 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a   an example of.*
2b320 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  * non-essential 
2b330 6d 65 6d 6f 72 79 2e 20 20 7b 46 31 36 33 34 32  memory.  {F16342
2b340 7d 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  } sqlite3_releas
2b350 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
2b360 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2b370 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
2b380 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20  ly freed, which 
2b390 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
2b3a0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68   less.** than th
2b3b0 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
2b3c0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2b3d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2b3e0 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
2b3f0 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65  API3REF:  Impose
2b400 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2b410 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a   Size {F17350}.*
2b420 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68  *.** {F16351} Th
2b430 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2b440 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2b450 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20  rface.** places 
2b460 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f  a "soft" limit o
2b470 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2b480 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2b490 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2b4a0 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20  d.** by SQLite. 
2b4b0 7b 46 31 36 33 35 32 7d 20 49 66 20 61 6e 20 69  {F16352} If an i
2b4c0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2b4d0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2b4e0 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65  .** that would e
2b4f0 78 63 65 65 64 20 74 68 65 20 73 6f 66 74 20 68  xceed the soft h
2b500 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
2b510 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2b520 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f  ry()] is.** invo
2b530 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ked one or more 
2b540 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
2b550 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
2b560 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
2b570 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 20 7b 45  n.** is made. {E
2b580 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ND}.**.** {F1635
2b590 33 7d 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  3} The limit is 
2b5a0 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
2b5b0 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71  ecause if.** [sq
2b5c0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2b5d0 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a  mory()] cannot.*
2b5e0 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  * free sufficien
2b5f0 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
2b600 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
2b610 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
2b620 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
2b630 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
2b640 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
2b650 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
2b660 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  roceeds..**.** {
2b670 46 31 36 33 35 34 7d 0a 2a 2a 20 41 20 6e 65 67  F16354}.** A neg
2b680 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
2b690 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
2b6a0 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
2b6b0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2b6c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2b6d0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2b6e0 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
2b6f0 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
2b700 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
2b710 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65  .** {F16355} The
2b720 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2b730 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2b740 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2b750 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
2b760 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2b770 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2b780 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
2b790 0a 2a 2a 20 7b 46 31 36 33 35 36 7d 20 42 75 74  .** {F16356} But
2b7a0 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
2b7b0 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 68  p limit cannot h
2b7c0 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
2b7d0 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
2b7e0 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72  ue without error
2b7f0 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e   or notification
2b800 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 20 69 73  . {END}  This is
2b810 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
2b820 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22  s .** called a "
2b830 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74  soft" limit.  It
2b840 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
2b850 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  y..**.** Prior t
2b860 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
2b870 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75   3.5.0, this rou
2b880 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72  tine only constr
2b890 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79  ained the memory
2b8a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  .** allocated by
2b8b0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
2b8c0 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65   - the same thre
2b8d0 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73  ad in which this
2b8e0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73   routine.** runs
2b8f0 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  .  Beginning wit
2b900 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
2b910 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74   3.5.0, the soft
2b920 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a   heap limit is.*
2b930 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c  * applied to all
2b940 20 74 68 72 65 61 64 73 2e 20 7b 46 31 36 33 35   threads. {F1635
2b950 37 7d 20 54 68 65 20 76 61 6c 75 65 20 73 70 65  7} The value spe
2b960 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73  cified for the s
2b970 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
2b980 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f  * is an upper bo
2b990 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c  und on the total
2b9a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2b9b0 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61  on for all threa
2b9c0 64 73 2e 20 7b 45 4e 44 7d 20 20 49 6e 0a 2a 2a  ds. {END}  In.**
2b9d0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
2b9e0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
2b9f0 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
2ba00 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
2ba10 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
2ba20 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  al threads..*/.v
2ba30 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2ba40 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2ba50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ba60 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61  F:  Extract Meta
2ba70 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2ba80 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
2ba90 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12850}.**.** Th
2baa0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
2bab0 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20  turns meta-data 
2bac0 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
2bad0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
2bae0 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a  cific database.*
2baf0 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  * table accessib
2bb00 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e  le using the con
2bb10 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70  nection handle p
2bb20 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
2bb30 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  st function .** 
2bb40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2bb50 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
2bb60 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2bb70 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
2bb80 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2bb90 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20  ers to .** this 
2bba0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
2bbb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2bbc0 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
2bbd0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2bbe0 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
2bbf0 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
2bc00 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2bc10 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2bc20 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2bc30 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
2bc40 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
2bc50 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
2bc60 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
2bc70 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
2bc80 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
2bc90 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
2bca0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
2bcb0 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a  engine uses to .
2bcc0 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2bcd0 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2bce0 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
2bcf0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2bd00 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2bd10 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2bd20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2bd30 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d  d column .** nam
2bd40 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2bd50 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2bd60 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2bd70 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2bd80 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  rs .** may be NU
2bd90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69  LL..**.** Meta i
2bda0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2bdb0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
2bdc0 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
2bdd0 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
2bde0 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61   as.** the 5th a
2bdf0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
2be00 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2be10 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
2be20 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75  f these .** argu
2be30 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c  ments may be NUL
2be40 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2be50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2be60 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2be70 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ta .** informati
2be80 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a  on is ommitted..
2be90 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50  **.** <pre>.** P
2bea0 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74  arameter     Out
2beb0 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65  put Type      De
2bec0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d  scription.** ---
2bed0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
2bee0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
2bef0 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20  .**.**   5th    
2bf00 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
2bf10 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a        Data type.
2bf20 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20  **   6th        
2bf30 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
2bf40 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65    Name of the de
2bf50 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
2bf60 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37  sequence .**   7
2bf70 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
2bf80 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
2bf90 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68   if the column h
2bfa0 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
2bfb0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74  nstraint.**   8t
2bfc0 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
2bfd0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
2bfe0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  if the column is
2bff0 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
2c000 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74  MARY KEY.**   9t
2c010 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
2c020 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
2c030 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  if the column is
2c040 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a   AUTOINCREMENT.*
2c050 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a  * </pre>.**.**.*
2c060 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69  * The memory poi
2c070 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
2c080 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
2c090 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
2c0a0 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  he .** declarati
2c0b0 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
2c0c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2c0d0 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
2c0e0 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20  il the next .** 
2c0f0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69  call to any sqli
2c100 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
2c110 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
2c120 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
2c130 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
2c140 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  , then an error 
2c150 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2c160 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
2c170 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2c180 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2c190 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2c1a0 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49   .** INTEGER PRI
2c1b0 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20  MARY KEY column 
2c1c0 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
2c1d0 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
2c1e0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a  en the output .*
2c1f0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2c200 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2c210 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2c220 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72   column. If ther
2c230 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
2c240 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49  citly declared I
2c250 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  PK column, then 
2c260 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d  the output param
2c270 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
2c280 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a   .** follows:.**
2c290 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2c2a0 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2c2b0 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2c2c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2c2d0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2c2e0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2c2f0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2c300 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2c310 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2c320 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  /pre>.**.** This
2c330 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
2c340 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
2c350 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
2c360 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
2c370 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
2c380 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
2c390 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
2c3a0 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
2c3b0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
2c3c0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
2c3d0 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63  n SQLITE error c
2c3e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2c3f0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
2c400 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20  sage.** left in 
2c410 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  the database han
2c420 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69  dle (to be retri
2c430 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  eved using sqlit
2c440 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a  e3_errmsg())..**
2c450 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20  .** This API is 
2c460 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2c470 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2c480 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2c490 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  the.** SQLITE_EN
2c4a0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2c4b0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
2c4c0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
2c4d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c4e0 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
2c4f0 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
2c500 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2c510 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
2c520 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
2c530 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
2c540 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
2c550 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
2c560 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
2c570 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
2c580 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
2c590 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
2c5a0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
2c5b0 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
2c5c0 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
2c5d0 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
2c5e0 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
2c5f0 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
2c600 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
2c610 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
2c620 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
2c630 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2c640 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
2c650 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20  *pNotNull,      
2c660 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2c670 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e  T: True if NOT N
2c680 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65  ULL constraint e
2c690 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a  xists */.  int *
2c6a0 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20  pPrimaryKey,    
2c6b0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2c6c0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
2c6d0 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20   part of PK */. 
2c6e0 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20   int *pAutoinc  
2c6f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c700 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
2c710 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69  column is auto-i
2c720 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a  ncrement */.);..
2c730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c740 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
2c750 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a  n {F12600}.**.**
2c760 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73 71   {F12601} The sq
2c770 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2c780 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2c790 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f 20  .** attempts to 
2c7a0 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65  load an SQLite e
2c7b0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2c7c0 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2c7d0 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e  e file.** zFile.
2c7e0 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65 6e   {F12602} The en
2c7f0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
2c800 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50 72  oc. {F12603} zPr
2c810 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20 69  oc may be 0.** i
2c820 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2c830 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
2c840 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74  ry point default
2c850 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65 33  s.** to "sqlite3
2c860 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2c870 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34 7d  ..**.** {F12604}
2c880 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2c890 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2c8a0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a 2a  terface shall.**
2c8b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c8c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
2c8d0 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  nd [SQLITE_ERROR
2c8e0 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  ] if something g
2c8f0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a  oes wrong..**.**
2c900 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66 20   {F12605}.** If 
2c910 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2c920 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
2c930 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
2c940 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  ** sqlite3_load_
2c950 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
2c960 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2c970 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a 45  mpt to fill *pzE
2c980 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65  rrMsg with .** e
2c990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2c9a0 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
2c9b0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c9c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c9d0 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54  ()]..** {END}  T
2c9e0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2c9f0 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 20  ion should free 
2ca00 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62  this memory.** b
2ca10 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2ca20 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2ca30 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45 78  * {F12606}.** Ex
2ca40 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ca50 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
2ca60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
2ca70 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2ca80 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  sion()].** prior
2ca90 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2caa0 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72   API or an error
2cab0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
2cac0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2cad0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2cae0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2caf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61            /* Loa
2cb00 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  d the extension 
2cb10 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61  into this databa
2cb20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f  se connection */
2cb30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2cb40 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65  File,    /* Name
2cb50 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c   of the shared l
2cb60 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ibrary containin
2cb70 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20  g extension */. 
2cb80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72   const char *zPr
2cb90 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20  oc,    /* Entry 
2cba0 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20  point.  Derived 
2cbb0 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20  from zFile if 0 
2cbc0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
2cbd0 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75  rMsg       /* Pu
2cbe0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  t error message 
2cbf0 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f  here if not 0 */
2cc00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2cc10 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20  REF:  Enable Or 
2cc20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
2cc30 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 32  n Loading {F1262
2cc40 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e  0}.**.** So as n
2cc50 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
2cc60 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
2cc70 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
2cc80 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
2cc90 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
2cca0 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
2ccb0 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
2ccc0 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
2ccd0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
2cce0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
2ccf0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
2cd00 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
2cd10 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20  ollowing.** API 
2cd20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
2cd30 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
2cd40 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2cd50 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
2cd60 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46 31  and.** off.  {F1
2cd70 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66 20  2622} It is off 
2cd80 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44  by default. {END
2cd90 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  } See ticket #18
2cda0 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32  63..**.** {F1262
2cdb0 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  1} Call the sqli
2cdc0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2cdd0 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
2cde0 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f 66  ine.** with onof
2cdf0 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78 74  f==1 to turn ext
2ce00 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f  ension loading o
2ce10 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74  n.** and call it
2ce20 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
2ce30 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20 6f  o turn it back o
2ce40 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a  ff again. {END}.
2ce50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2ce60 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2ce70 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
2ce80 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
2ce90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
2cea0 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73  ake Arrangements
2ceb0 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c   To Automaticall
2cec0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
2ced0 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a  ion {F12640}.**.
2cee0 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69 73  ** {F12641} This
2cef0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 67   function.** reg
2cf00 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73  isters an extens
2cf10 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
2cf20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69  that is automati
2cf30 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a  cally invoked.**
2cf40 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2cf50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cf60 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73  ion is opened us
2cf70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2cf80 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2cf90 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20  3_open16()], or 
2cfa0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2cfb0 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ()]. {END}.**.**
2cfc0 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65   This API can be
2cfd0 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
2cfe0 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
2cff0 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
2d000 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
2d010 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
2d020 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
2d030 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
2d040 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
2d050 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
2d060 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ctions..**.** {F
2d070 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65  12642} Duplicate
2d080 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20   extensions are 
2d090 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c  detected so call
2d0a0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
2d0b0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2d0c0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2d0d0 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61   extension is ha
2d0e0 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rmless..**.** {F
2d0f0 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74  12643} This rout
2d100 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69  ine stores a poi
2d110 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65  nter to the exte
2d120 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61  nsion in an arra
2d130 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74  y.** that is obt
2d140 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
2d150 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44  e_malloc(). {END
2d160 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d  } If you run a m
2d170 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68  emory leak.** ch
2d180 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72  ecker on your pr
2d190 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70  ogram and it rep
2d1a0 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61  orts a leak beca
2d1b0 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61  use of this.** a
2d1c0 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rray, then invok
2d1d0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2d1e0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2d1f0 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73  )] prior.** to s
2d200 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20  hutdown to free 
2d210 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  the memory..**.*
2d220 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f 6d  * {F12644} Autom
2d230 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
2d240 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  apply across all
2d250 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a   threads. {END}.
2d260 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2d270 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65  face is experime
2d280 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a  ntal and is subj
2d290 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
2d2a0 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66  .** removal in f
2d2b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2d2c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
2d2d0 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
2d2e0 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45  tension(void *xE
2d2f0 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a  ntryPoint);.../*
2d300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2d310 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2d320 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2d330 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12660}.**.** {
2d340 46 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e  F12661} This fun
2d350 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2d360 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2d370 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74 6f  gistered.** auto
2d380 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2d390 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a 2a  . {END}  This.**
2d3a0 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
2d3b0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c  the effect of al
2d3c0 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65 33  l prior [sqlite3
2d3d0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2d3e0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  )].** calls..**.
2d3f0 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69 73  ** {F12662} This
2d400 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61   call disabled a
2d410 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
2d420 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
2d430 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
2d440 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
2d450 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
2d460 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
2d470 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
2d480 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
2d490 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2d4a0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  te..*/.void sqli
2d4b0 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
2d4c0 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
2d4d0 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ../*.****** EXPE
2d4e0 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
2d4f0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
2d500 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
2d510 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a  **********.**.**
2d520 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
2d530 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
2d540 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
2d550 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
2d560 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
2d570 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
2d580 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
2d590 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
2d5a0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
2d5b0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
2d5c0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
2d5d0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
2d5e0 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
2d5f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
2d600 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
2d610 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
2d620 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  ablizes, we will
2d630 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
2d640 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
2d650 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
2d660 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
2d670 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
2d680 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
2d690 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
2d6a0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2d6b0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
2d6c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2d6d0 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
2d6e0 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
2d6f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2d700 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
2d710 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
2d720 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2d730 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2d740 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
2d750 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
2d760 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
2d770 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
2d780 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f  ule;../*.** A mo
2d790 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20  dule is a class 
2d7a0 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  of virtual table
2d7b0 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  s.  Each module 
2d7c0 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  is defined.** by
2d7d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
2d7e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2d7f0 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73  ructure.  This s
2d800 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
2d810 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  s.** mostly of m
2d820 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2d830 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  odule..*/.struct
2d840 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2d850 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
2d860 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
2d870 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
2d880 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2d890 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2d8a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2d8b0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2d8c0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2d8d0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2d8e0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2d8f0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
2d900 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2d910 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d920 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2d930 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2d940 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d950 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2d960 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2d970 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
2d980 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
2d990 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
2d9a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
2d9b0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
2d9c0 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
2d9d0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2d9e0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
2d9f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2da00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
2da10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2da20 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
2da30 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
2da40 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
2da50 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
2da60 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
2da70 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
2da80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2da90 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
2daa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
2dab0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
2dac0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2dad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
2dae0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
2daf0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
2db00 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
2db10 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
2db20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
2db30 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
2db40 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
2db50 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
2db60 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2db70 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
2db80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2db90 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
2dba0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
2dbb0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
2dbc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
2dbd0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
2dbe0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
2dbf0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
2dc00 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
2dc10 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2dc20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
2dc30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2dc40 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
2dc50 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
2dc60 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2dc70 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
2dc80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2dc90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
2dca0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
2dcb0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
2dcc0 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
2dcd0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
2dce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dcf0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
2dd00 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2dd10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2dd20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
2dd30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dd40 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
2dd50 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ..  int (*xRenam
2dd60 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
2dd70 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
2dd80 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
2dd90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2dda0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
2ddb0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
2ddc0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
2ddd0 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
2dde0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
2ddf0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
2de00 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78  reply from the x
2de10 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74  BestIndex.** met
2de20 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  hod of an sqlite
2de30 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66  3_module.  The f
2de40 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
2de50 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
2de60 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
2de70 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
2de80 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
2de90 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
2dea0 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
2deb0 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
2dec0 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
2ded0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
2dee0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
2def0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
2df00 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a  straints of the.
2df10 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20  ** form:.**.**  
2df20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50         column OP
2df30 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72   expr.**.** Wher
2df40 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
2df50 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
2df60 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65   &gt;=.  .** The
2df70 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
2df80 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a  ator is stored.*
2df90 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  * in aConstraint
2dfa0 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
2dfb0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2dfc0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a  is stored in .**
2dfd0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
2dfe0 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
2dff0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
2e000 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
2e010 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
2e020 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
2e030 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
2e040 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
2e050 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
2e060 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
2e070 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
2e080 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
2e090 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2e0a0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
2e0b0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
2e0c0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
2e0d0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
2e0e0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
2e0f0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
2e100 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
2e110 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
2e120 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
2e130 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
2e140 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
2e150 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
2e160 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
2e170 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
2e180 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
2e190 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
2e1a0 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
2e1b0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
2e1c0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
2e1d0 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
2e1e0 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
2e1f0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2e200 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2e210 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
2e220 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
2e230 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
2e240 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
2e250 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
2e260 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
2e270 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  ** The xBestInde
2e280 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  x method must fi
2e290 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
2e2a0 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
2e2b0 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
2e2c0 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
2e2d0 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
2e2e0 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65  er.  If argvInde
2e2f0 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
2e300 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
2e310 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
2e320 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
2e330 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
2e340 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
2e350 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
2e360 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
2e370 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
2e380 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
2e390 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
2e3a0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
2e3b0 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
2e3c0 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
2e3d0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
2e3e0 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
2e3f0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
2e400 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2e410 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
2e420 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
2e430 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
2e440 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a   into xFilter..*
2e450 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  * sqlite3_free()
2e460 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
2e470 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54   idxPtr if needT
2e480 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
2e490 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
2e4a0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
2e4b0 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
2e4c0 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69   from xFilter wi
2e4d0 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
2e4e0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
2e4f0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
2e500 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
2e510 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
2e520 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
2e530 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
2e540 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
2e550 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
2e560 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
2e570 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
2e580 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
2e590 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
2e5a0 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
2e5b0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
2e5c0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
2e5d0 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
2e5e0 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
2e5f0 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
2e600 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
2e610 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
2e620 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
2e630 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
2e640 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e650 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
2e660 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
2e670 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
2e680 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
2e690 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
2e6a0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
2e6b0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2e6c0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
2e6d0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
2e6e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2e6f0 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
2e700 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
2e710 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
2e720 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
2e730 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
2e740 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
2e750 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
2e760 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
2e770 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
2e780 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
2e790 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
2e7a0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
2e7b0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
2e7c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
2e7d0 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
2e7e0 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
2e7f0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
2e800 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
2e810 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
2e820 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
2e830 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
2e840 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
2e850 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2e860 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
2e870 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
2e880 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e890 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
2e8a0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
2e8b0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
2e8c0 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
2e8d0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
2e8e0 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
2e8f0 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
2e900 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
2e910 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
2e920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e930 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
2e940 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75  ause */..  /* Ou
2e950 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
2e960 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2e970 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
2e980 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
2e990 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
2e9a0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
2e9b0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
2e9c0 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
2e9d0 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
2e9e0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
2e9f0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
2ea00 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
2ea10 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
2ea20 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
2ea30 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
2ea40 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
2ea50 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
2ea60 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
2ea70 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
2ea80 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
2ea90 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
2eaa0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
2eab0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
2eac0 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
2ead0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
2eae0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
2eaf0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
2eb00 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
2eb10 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
2eb20 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
2eb30 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
2eb40 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
2eb50 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
2eb60 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
2eb70 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
2eb80 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
2eb90 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
2eba0 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
2ebb0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2ebc0 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
2ebd0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2ebe0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
2ebf0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2ec00 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2ec10 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
2ec20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
2ec30 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
2ec40 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
2ec50 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
2ec60 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
2ec70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
2ec80 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
2ec90 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68  TCH 64../*.** Th
2eca0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
2ecb0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
2ecc0 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   new module name
2ecd0 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a   with an SQLite.
2ece0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
2ecf0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
2ed00 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
2ed10 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20  before creating 
2ed20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  new.** virtual t
2ed30 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64  ables on the mod
2ed40 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75  ule, or before u
2ed50 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67  sing preexisting
2ed60 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
2ed70 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  es of the module
2ed80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ed90 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
2eda0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2edb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2edc0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
2edd0 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
2ede0 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
2edf0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2ee00 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
2ee10 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
2ee20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
2ee30 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20  e3_module *,    
2ee40 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
2ee50 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
2ee60 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20  oid *           
2ee70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
2ee80 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
2ee90 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
2eea0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20  .);../*.** This 
2eeb0 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74  routine is ident
2eec0 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69  ical to the sqli
2eed0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2eee0 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65  e() method above
2eef0 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ,.** except that
2ef00 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73   it allows a des
2ef10 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2ef20 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64   to be specified
2ef30 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20  . It is.** even 
2ef40 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61  more experimenta
2ef50 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20  l than the rest 
2ef60 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
2ef70 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e  ables API..*/.in
2ef80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2ef90 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
2efa0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2efb0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
2efc0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
2efd0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
2efe0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
2eff0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
2f000 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
2f010 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
2f020 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
2f030 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
2f040 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2f050 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
2f060 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
2f070 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
2f080 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
2f090 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
2f0a0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2f0b0 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
2f0c0 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
2f0d0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
2f0e0 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c  *.** Every modul
2f0f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f100 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
2f110 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2f120 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74  g structure.** t
2f130 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
2f140 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
2f150 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
2f160 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
2f170 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
2f180 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
2f190 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
2f1a0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
2f1b0 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20  ation.   The.** 
2f1c0 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20  purpose of this 
2f1d0 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f  superclass is to
2f1e0 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20   define certain 
2f1f0 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20  fields that are 
2f200 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c  common.** to all
2f210 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
2f220 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56  tations..**.** V
2f230 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
2f240 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
2f250 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
2f260 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
2f270 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
2f280 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
2f290 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d  rintf() to zErrM
2f2a0 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
2f2b0 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
2f2c0 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
2f2d0 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
2f2e0 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
2f2f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a  sqlite3_free().*
2f300 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
2f310 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
2f320 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41  g to zErrMsg.  A
2f330 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
2f340 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
2f350 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
2f360 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
2f370 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
2f380 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2f390 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
2f3a0 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
2f3b0 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
2f3c0 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
2f3d0 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20  eroed.  Note.** 
2f3e0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72  that sqlite3_mpr
2f3f0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
2f400 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73  e3_free() are us
2f410 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73  ed on the zErrMs
2f420 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65  g field.** since
2f430 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
2f440 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70  are commonly imp
2f450 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64  lemented in load
2f460 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  able extensions 
2f470 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20  which.** do not 
2f480 68 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73  have access to s
2f490 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20  qlite3MPrintf() 
2f4a0 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29  or sqlite3Free()
2f4b0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
2f4c0 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
2f4d0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
2f4e0 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
2f4f0 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
2f500 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
2f510 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
2f520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f530 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
2f540 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63  nternally */.  c
2f550 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
2f560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2f570 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
2f580 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
2f590 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
2f5a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
2f5b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
2f5c0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
2f5d0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
2f5e0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72  s */.};../* Ever
2f5f0 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  y module impleme
2f600 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
2f610 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66  ubclass of the f
2f620 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
2f630 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62  re.** to describ
2f640 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
2f650 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69  oint into the vi
2f660 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
2f670 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
2f680 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
2f690 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
2f6a0 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
2f6b0 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
2f6c0 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
2f6d0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
2f6e0 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
2f6f0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
2f700 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
2f710 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
2f720 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
2f730 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
2f740 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
2f750 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
2f760 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
2f770 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
2f780 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
2f790 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
2f7a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
2f7b0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2f7c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
2f7d0 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
2f7e0 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
2f7f0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
2f800 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
2f810 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
2f820 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2f830 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
2f840 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
2f850 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
2f860 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65  *.** The xCreate
2f870 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65   and xConnect me
2f880 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c  thods of a modul
2f890 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77  e use the follow
2f8a0 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65  ing API.** to de
2f8b0 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
2f8c0 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
2f8d0 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
2f8e0 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
2f8f0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2f900 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
2f910 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2f920 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
2f930 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
2f940 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c  har *zCreateTabl
2f950 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75  e);../*.** Virtu
2f960 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72  al tables can pr
2f970 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76  ovide alternativ
2f980 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f990 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  s of functions.*
2f9a0 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e  * using the xFin
2f9b0 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64  dFunction method
2f9c0 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  .  But global ve
2f9d0 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
2f9e0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
2f9f0 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
2fa00 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
2fa10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  d..**.** This AP
2fa20 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67  I makes sure a g
2fa30 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66  lobal version of
2fa40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2fa50 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
2fa60 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72   name and number
2fa70 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65   of parameters e
2fa80 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75  xists.  If no su
2fa90 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73  ch function exis
2faa0 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  ts.** before thi
2fab0 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c  s API is called,
2fac0 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20   a new function 
2fad0 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
2fae0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
2faf0 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75  ** of the new fu
2fb00 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61  nction always ca
2fb10 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f  uses an exceptio
2fb20 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20  n to be thrown. 
2fb30 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66   So.** the new f
2fb40 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
2fb50 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67  ood for anything
2fb60 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73   by itself.  Its
2fb70 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65   only.** purpose
2fb80 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63   is to be a plac
2fb90 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  e-holder functio
2fba0 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
2fbb0 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76  erloaded.** by v
2fbc0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a  irtual tables..*
2fbd0 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68  *.** This API sh
2fbe0 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72  ould be consider
2fbf0 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76  ed part of the v
2fc00 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
2fc10 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68  erface,.** which
2fc20 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
2fc30 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20   and subject to 
2fc40 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
2fc50 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
2fc60 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
2fc70 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2fc80 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
2fc90 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
2fca0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
2fcb0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
2fcc0 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
2fcd0 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
2fce0 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
2fcf0 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
2fd00 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
2fd10 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
2fd20 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
2fd30 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
2fd40 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
2fd50 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
2fd60 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
2fd70 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
2fd80 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
2fd90 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
2fda0 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
2fdb0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
2fdc0 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
2fdd0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
2fde0 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
2fdf0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
2fe00 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
2fe10 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
2fe20 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
2fe30 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
2fe40 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20  ment..**.****** 
2fe50 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
2fe60 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2fe70 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
2fe80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
2fe90 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2fea0 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
2feb0 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37  n Open BLOB {F17
2fec0 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  800}.**.** An in
2fed0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
2fee0 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73  llowing opaque s
2fef0 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64  tructure is used
2ff00 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e   to .** represen
2ff10 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65  t an blob-handle
2ff20 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65  .  A blob-handle
2ff30 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a   is created by.*
2ff40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2ff50 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74  open()] and dest
2ff60 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2ff70 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
2ff80 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2ff90 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
2ffa0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
2ffb0 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
2ffc0 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
2ffd0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
2ffe0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
2fff0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f  tions of the blo
30000 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  b..** The [sqlit
30010 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
30020 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30030 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
30040 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79  he.** blob in by
30050 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
30060 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
30070 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
30080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30090 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
300a0 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
300b0 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a  /O {F17810}.**.*
300c0 2a 20 7b 46 31 37 38 31 31 7d 20 54 68 69 73 20  * {F17811} This 
300d0 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
300e0 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65   a handle to the
300f0 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a   blob located.**
30100 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63   in row iRow,, c
30110 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
30120 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
30130 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
30140 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
30150 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74   the same blob t
30160 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
30170 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
30180 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
30190 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
301a0 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
301b0 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a  E rowid = iRow;.
301c0 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a  ** </pre> {END}.
301d0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 32 7d 20 49  **.** {F17812} I
301e0 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
301f0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
30200 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
30210 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65  pened for .** re
30220 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63  ad and write acc
30230 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65  ess. If it is ze
30240 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
30250 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
30260 0a 2a 2a 20 61 63 63 65 73 73 2e 20 7b 45 4e 44  .** access. {END
30270 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d  }.**.** {F17813}
30280 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
30290 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
302a0 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
302b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
302c0 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ob | blob handle
302d0 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  ] is written to 
302e0 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 7b 46 31  *ppBlob. .** {F1
302f0 37 38 31 34 7d 20 4f 74 68 65 72 77 69 73 65 20  7814} Otherwise 
30300 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  an error code is
30310 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a   returned and .*
30320 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74  * any value writ
30330 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73  ten to *ppBlob s
30340 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
30350 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  d by the caller.
30360 0a 2a 2a 20 7b 46 31 37 38 31 35 7d 20 54 68 69  .** {F17815} Thi
30370 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
30380 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e  the database-han
30390 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  dle error code a
303a0 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
303b0 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
303c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
303d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
303e0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3c 74 6f 64  rmsg()]..** <tod
303f0 6f 3e 57 65 20 73 68 6f 75 6c 64 20 67 6f 20 74  o>We should go t
30400 68 72 6f 75 67 68 20 61 6e 64 20 6d 61 72 6b 20  hrough and mark 
30410 61 6c 6c 20 69 6e 74 65 72 66 61 63 65 73 20 74  all interfaces t
30420 68 61 74 20 62 65 68 61 76 65 20 74 68 69 73 0a  hat behave this.
30430 2a 2a 20 77 61 79 20 77 69 74 68 20 61 20 73 69  ** way with a si
30440 6d 69 6c 61 72 20 73 74 61 74 65 6d 65 6e 74 3c  milar statement<
30450 2f 74 6f 64 6f 3e 0a 2a 2f 0a 69 6e 74 20 73 71  /todo>.*/.int sq
30460 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
30470 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
30480 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
30490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
304a0 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
304b0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
304c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
304d0 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
304e0 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
304f0 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
30500 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f  * CAPI3REF:  Clo
30510 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
30520 20 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F17830}.**.** 
30530 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73  Close an open [s
30540 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
30550 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  ob handle]..**.*
30560 2a 20 7b 46 31 37 38 33 31 7d 20 43 6c 6f 73 69  * {F17831} Closi
30570 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20  ng a BLOB shall 
30580 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e  cause the curren
30590 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  t transaction to
305a0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68   commit.** if th
305b0 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72  ere are no other
305c0 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69   BLOBs, no pendi
305d0 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ng prepared stat
305e0 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a  ements, and the.
305f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
30600 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74  ection is in aut
30610 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a  ocommit mode..**
30620 20 7b 46 31 37 38 33 32 7d 20 49 66 20 61 6e 79   {F17832} If any
30630 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
30640 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
30650 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
30660 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
30670 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
30680 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
30690 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a  will fit. {END}.
306a0 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42  ** Closing the B
306b0 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
306c0 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
306d0 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
306e0 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
306f0 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
30700 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
30710 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
30720 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
30730 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37  is closed.  {F17
30740 38 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20  833} Any errors 
30750 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e  that occur durin
30760 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65  g.** closing are
30770 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e   reported as a n
30780 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76  on-zero return v
30790 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  alue..**.** {F17
307a0 38 33 39 7d 20 54 68 65 20 42 4c 4f 42 20 69 73  839} The BLOB is
307b0 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
307c0 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
307d0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
307e0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
307f0 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
30800 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
30810 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
30820 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c  3_blob_close(sql
30830 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
30840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
30850 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
30860 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  Of An Open BLOB 
30870 7b 46 31 37 38 30 35 7d 0a 2a 2a 0a 2a 2a 20 7b  {F17805}.**.** {
30880 46 31 36 38 30 36 7d 20 52 65 74 75 72 6e 20 74  F16806} Return t
30890 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
308a0 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63   of the blob acc
308b0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
308c0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
308d0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
308e0 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20  ndle] passed as 
308f0 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a  an argument..*/.
30900 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
30910 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
30920 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
30930 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44  API3REF:  Read D
30940 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20  ata From A BLOB 
30950 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46  Incrementally {F
30960 31 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  17850}.**.** Thi
30970 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
30980 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
30990 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a  from an open .**
309a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
309b0 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e   blob-handle] in
309c0 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70  to a caller supp
309d0 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20  lied buffer..** 
309e0 7b 46 31 37 38 35 31 7d 20 6e 20 62 79 74 65 73  {F17851} n bytes
309f0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
30a00 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a  ied into buffer.
30a10 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70  ** z from the op
30a20 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
30a30 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
30a40 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  set..**.** {F178
30a50 35 32 7d 20 49 66 20 6f 66 66 73 65 74 20 69 4f  52} If offset iO
30a60 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
30a70 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20  an n bytes from 
30a80 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62  the end of the b
30a90 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  lob, .** [SQLITE
30aa0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
30ab0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
30ac0 69 73 20 72 65 61 64 2e 20 20 7b 46 31 37 38 35  is read.  {F1785
30ad0 33 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65  3} If n is.** le
30ae0 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
30af0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
30b00 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
30b10 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a  ata is read..**.
30b20 2a 2a 20 7b 46 31 37 38 35 34 7d 20 4f 6e 20 73  ** {F17854} On s
30b30 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f  uccess, SQLITE_O
30b40 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  K is returned. O
30b50 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a  therwise, an .**
30b60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
30b70 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
30b80 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
30b90 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
30ba0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
30bb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
30bc0 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20  void *z, int n, 
30bd0 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
30be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
30bf0 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
30c00 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
30c10 61 6c 6c 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a  ally {F17870}.**
30c20 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
30c30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
30c40 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
30c50 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
30c60 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
30c70 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65  ndle] from a use
30c80 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r supplied buffe
30c90 72 2e 0a 2a 2a 20 7b 46 31 37 38 37 31 7d 20 6e  r..** {F17871} n
30ca0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
30cb0 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
30cc0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69  he buffer.** poi
30cd0 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74  nted to by z int
30ce0 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  o the open blob,
30cf0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
30d00 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
30d10 2a 2a 20 7b 46 31 37 38 37 32 7d 20 49 66 20 74  ** {F17872} If t
30d20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
30d30 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
30d40 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
30d50 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
30d60 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66  was not opened f
30d70 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  or writing (the 
30d80 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
30d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
30da0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73  _open()].*** was
30db0 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e   zero), this fun
30dc0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
30dd0 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e  QLITE_READONLY].
30de0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 33 7d 20  .**.** {F17873} 
30df0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
30e00 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
30e10 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
30e20 65 20 62 6c 6f 62 3b 20 69 74 20 69 73 0a 2a 2a  e blob; it is.**
30e30 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
30e40 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
30e50 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69  ze of a blob usi
30e60 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20  ng this API..** 
30e70 7b 46 31 37 38 37 34 7d 20 49 66 20 6f 66 66 73  {F17874} If offs
30e80 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65  et iOffset is le
30e90 73 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20  ss than n bytes 
30ea0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20  from the end of 
30eb0 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53  the blob, .** [S
30ec0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
30ed0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
30ee0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
30ef0 20 20 7b 46 31 37 38 37 35 7d 20 49 66 20 6e 20    {F17875} If n 
30f00 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
30f10 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
30f20 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
30f30 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
30f40 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ritten..**.** {F
30f50 31 37 38 37 36 7d 20 4f 6e 20 73 75 63 63 65 73  17876} On succes
30f60 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
30f70 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77  returned. Otherw
30f80 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72  ise, an .** [err
30f90 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
30fa0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
30fb0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
30fc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30fd0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
30fe0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
30ff0 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
31000 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
31010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31020 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53    Virtual File S
31030 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 46  ystem Objects {F
31040 31 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 76  11200}.**.** A v
31050 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65  irtual filesyste
31060 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73  m (VFS) is an [s
31070 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
31080 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ct.** that SQLit
31090 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61  e uses to intera
310a0 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75  ct.** with the u
310b0 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
310c0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73  ing system.  Mos
310d0 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  t builds come wi
310e0 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
310f0 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
31100 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
31110 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
31120 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
31130 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
31140 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
31150 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
31160 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
31170 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
31180 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
31190 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  vided..**.** {F1
311a0 31 32 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65  1201} The sqlite
311b0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
311c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
311d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20   pointer to .** 
311e0 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20  a VFS given its 
311f0 6e 61 6d 65 2e 20 20 7b 46 31 31 32 30 32 7d 20  name.  {F11202} 
31200 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
31210 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 7b 46 31  ensitive..** {F1
31220 31 32 30 33 7d 20 4e 61 6d 65 73 20 61 72 65 20  1203} Names are 
31230 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
31240 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
31250 2a 20 7b 46 31 31 32 30 34 7d 20 49 66 20 74 68  * {F11204} If th
31260 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
31270 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
31280 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
31290 7b 46 31 31 32 30 35 7d 20 49 66 20 7a 56 66 73  {F11205} If zVfs
312a0 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
312b0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a  n the default .*
312c0 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  * VFS is returne
312d0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  d. {END}.**.** {
312e0 46 31 31 32 31 30 7d 20 4e 65 77 20 56 46 53 65  F11210} New VFSe
312f0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
31300 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66   with sqlite3_vf
31310 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a  s_register()..**
31320 20 7b 46 31 31 32 31 31 7d 20 45 61 63 68 20 6e   {F11211} Each n
31330 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74  ew VFS becomes t
31340 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
31350 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  f the makeDflt f
31360 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 7b  lag is set..** {
31370 46 31 31 32 31 32 7d 20 54 68 65 20 73 61 6d 65  F11212} The same
31380 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
31390 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
313a0 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
313b0 6a 75 72 79 2e 0a 2a 2a 20 7b 46 31 31 32 31 33  jury..** {F11213
313c0 7d 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69  } To make an exi
313d0 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74  sting VFS into t
313e0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20  he default VFS, 
313f0 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69  register it agai
31400 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61  n.** with the ma
31410 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e  keDflt flag set.
31420 20 7b 55 31 31 32 31 34 7d 20 49 66 20 74 77 6f   {U11214} If two
31430 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73   different VFSes
31440 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d   with the.** sam
31450 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73  e name are regis
31460 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76  tered, the behav
31470 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
31480 2e 20 20 7b 55 31 31 32 31 35 7d 20 49 66 20 61  .  {U11215} If a
31490 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73  .** VFS is regis
314a0 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d  tered with a nam
314b0 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f  e that is NULL o
314c0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
314d0 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  g,.** then the b
314e0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
314f0 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  ined..** .** {F1
31500 31 32 32 30 7d 20 55 6e 72 65 67 69 73 74 65 72  1220} Unregister
31510 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
31520 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
31530 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
31540 63 65 2e 0a 2a 2a 20 7b 46 31 31 32 32 31 7d 20  ce..** {F11221} 
31550 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  If the default V
31560 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72  FS is unregister
31570 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20  ed, another VFS 
31580 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20  is chosen as.** 
31590 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68  the default.  Th
315a0 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65  e choice for the
315b0 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69   new VFS is arbi
315c0 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65  trary..*/.sqlite
315d0 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
315e0 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
315f0 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
31600 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
31610 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
31620 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
31630 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
31640 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
31650 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
31660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31670 4d 75 74 65 78 65 73 20 7b 46 31 37 30 30 30 7d  Mutexes {F17000}
31680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
31690 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
316a0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74  e routines for t
316b0 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f  hread.** synchro
316c0 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67  nization.  Thoug
316d0 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e  h they are inten
316e0 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ded for internal
316f0 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
31700 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e  e, code that lin
31710 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
31720 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65  e is.** permitte
31730 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20  d to use any of 
31740 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
31750 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
31760 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
31770 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69  tains multiple i
31780 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a  mplementations .
31790 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
317a0 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
317b0 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
317c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
317d0 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
317e0 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
317f0 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f  le-time.  The fo
31800 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65  llowing.** imple
31810 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61  mentations are a
31820 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
31830 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a  SQLite core:.**.
31840 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
31850 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f    SQLITE_MUTEX_O
31860 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  S2.** <li>   SQL
31870 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
31880 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  D.** <li>   SQLI
31890 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20  TE_MUTEX_W32.** 
318a0 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
318b0 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c  TEX_NOOP.** </ul
318c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
318d0 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d  TE_MUTEX_NOOP im
318e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
318f0 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65  a set of routine
31900 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  s .** that does 
31910 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20  no real locking 
31920 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61  and is appropria
31930 74 65 20 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a  te for use in .*
31940 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  * a single-threa
31950 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  ded application.
31960 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54    The SQLITE_MUT
31970 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54  EX_OS2,.** SQLIT
31980 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c  E_MUTEX_PTHREAD,
31990 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
319a0 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61  X_W32 implementa
319b0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70  tions.** are app
319c0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
319d0 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78 2c 20   on os/2, unix, 
319e0 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a 2a 20  and windows..** 
319f0 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73  .** If SQLite is
31a00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
31a10 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
31a20 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73  APPDEF preproces
31a30 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66  sor.** macro def
31a40 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51  ined (with "-DSQ
31a50 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
31a60 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d  F=1"), then no m
31a70 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
31a80 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64  tation is includ
31a90 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
31aa0 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74  ary.  The.** mut
31ab0 65 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  ex interface rou
31ac0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
31ad0 72 65 20 62 65 63 6f 6d 65 20 65 78 74 65 72 6e  re become extern
31ae0 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63 65 73  al.** references
31af0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 6c   in the SQLite l
31b00 69 62 72 61 72 79 20 66 6f 72 20 77 68 69 63 68  ibrary for which
31b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31b20 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72 6f 76  .** must be prov
31b30 69 64 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  ided by the appl
31b40 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 66  ication.  This f
31b50 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73 20 61  acility allows a
31b60 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
31b70 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
31b80 6e 73 74 20 53 51 4c 69 74 65 20 74 6f 20 70 72  nst SQLite to pr
31b90 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 6d 75  ovide its own mu
31ba0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
31bb0 61 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 68 61  ation without ha
31bc0 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79 20 74  ving to modify t
31bd0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a  he SQLite core..
31be0 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 31 7d 20 54  **.** {F17011} T
31bf0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
31c00 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
31c10 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
31c20 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
31c30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
31c40 74 6f 20 69 74 2e 20 7b 46 31 37 30 31 32 7d 20  to it. {F17012} 
31c50 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  If it returns NU
31c60 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73  LL.** that means
31c70 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f   that a mutex co
31c80 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63  uld not be alloc
31c90 61 74 65 64 2e 20 7b 46 31 37 30 31 33 7d 20 53  ated. {F17013} S
31ca0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
31cb0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
31cc0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
31cd0 6f 72 2e 20 7b 46 31 37 30 31 34 7d 20 54 68 65  or. {F17014} The
31ce0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
31cf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
31d00 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
31d10 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
31d20 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
31d30 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
31d40 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
31d50 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
31d60 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
31d70 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
31d80 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
31d90 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
31da0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
31db0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
31dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
31dd0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
31de0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
31df0 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
31e00 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
31e10 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f 75 6c  ATIC_LRU.** </ul
31e20 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  > {END}.**.** {F
31e30 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74  17015} The first
31e40 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
31e50 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
31e60 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
31e70 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
31e80 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
31e90 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
31ea0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
31eb0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
31ec0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
31ed0 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
31ee0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
31ef0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b  _FAST is used. {
31f00 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65  END}.** The mute
31f10 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
31f20 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
31f30 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
31f40 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
31f50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
31f60 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
31f70 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
31f80 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
31f90 61 6e 74 20 74 6f 2e 20 20 7b 46 31 37 30 31 36  ant to.  {F17016
31fa0 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c  } But SQLite wil
31fb0 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
31fc0 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
31fd0 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
31fe0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
31ff0 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49  ds one.  {END} I
32000 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72  f a faster non-r
32010 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a  ecursive mutex.*
32020 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32030 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e   is available on
32040 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f   the host platfo
32050 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75  rm, the mutex su
32060 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74  bsystem.** might
32070 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d   return such a m
32080 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65  utex in response
32090 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   to SQLITE_MUTEX
320a0 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  _FAST..**.** {F1
320b0 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20  7017} The other 
320c0 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
320d0 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
320e0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68  tex_alloc() each
320f0 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
32100 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
32110 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
32120 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20  ex. {END}  Four 
32130 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
32140 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
32150 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
32160 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
32170 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
32180 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
32190 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
321a0 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
321b0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
321c0 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
321d0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
321e0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
321f0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
32200 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
32210 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
32220 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
32230 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
32240 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
32250 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
32260 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
32270 2a 0a 2a 2a 20 7b 46 31 37 30 31 38 7d 20 4e 6f  *.** {F17018} No
32280 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f  te that if one o
32290 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  f the dynamic mu
322a0 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28  tex parameters (
322b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
322c0 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d  T.** or SQLITE_M
322d0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
322e0 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c  is used then sql
322f0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
32300 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
32310 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20  different mutex 
32320 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20  on every call.  
32330 7b 46 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72  {F17034} But for
32340 20 74 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20   the static .** 
32350 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
32360 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
32370 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
32380 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
32390 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
323a0 6e 75 6d 62 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  number. {END}.**
323b0 0a 2a 2a 20 7b 46 31 37 30 31 39 7d 20 54 68 65  .** {F17019} The
323c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
323d0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65  ree() routine de
323e0 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76  allocates a prev
323f0 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61  iously.** alloca
32400 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  ted dynamic mute
32410 78 2e 20 7b 46 31 37 30 32 30 7d 20 53 51 4c 69  x. {F17020} SQLi
32420 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f  te is careful to
32430 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72   deallocate ever
32440 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74  y.** dynamic mut
32450 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63  ex that it alloc
32460 61 74 65 73 2e 20 7b 55 31 37 30 32 31 7d 20 54  ates. {U17021} T
32470 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
32480 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69  es must not be i
32490 6e 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74  n .** use when t
324a0 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  hey are dealloca
324b0 74 65 64 2e 20 7b 55 31 37 30 32 32 7d 20 41 74  ted. {U17022} At
324c0 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c  tempting to deal
324d0 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a  locate a static.
324e0 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73  ** mutex results
324f0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
32500 68 61 76 69 6f 72 2e 20 7b 46 31 37 30 32 33 7d  havior. {F17023}
32510 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65   SQLite never de
32520 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73  allocates.** a s
32530 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e  tatic mutex. {EN
32540 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  D}.**.** The sql
32550 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
32560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
32570 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
32580 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
32590 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
325a0 20 7b 46 31 37 30 32 34 7d 20 49 66 20 61 6e 6f   {F17024} If ano
325b0 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
325c0 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
325d0 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
325e0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
325f0 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
32600 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
32610 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
32620 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
32630 20 7b 46 31 37 30 32 35 7d 20 20 54 68 65 20 73   {F17025}  The s
32640 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
32650 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32660 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a  urns SQLITE_OK.*
32670 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75  * upon successfu
32680 6c 20 65 6e 74 72 79 2e 20 20 7b 46 31 37 30 32  l entry.  {F1702
32690 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74  6} Mutexes creat
326a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ed using.** SQLI
326b0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
326c0 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65  VE can be entere
326d0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
326e0 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
326f0 65 61 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 37 7d  ead..** {F17027}
32700 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74   In such cases t
32710 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73  he,.** mutex mus
32720 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65  t be exited an e
32730 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74  qual number of t
32740 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74  imes before anot
32750 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61  her thread.** ca
32760 6e 20 65 6e 74 65 72 2e 20 20 7b 55 31 37 30 32  n enter.  {U1702
32770 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74  8} If the same t
32780 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
32790 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a  nter any other.*
327a0 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20  * kind of mutex 
327b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
327c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
327d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 46  undefined..** {F
327e0 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69  17029} SQLite wi
327f0 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
32800 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
32810 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
32820 20 6f 66 20 6d 75 74 65 78 65 73 2e 20 7b 45 4e   of mutexes. {EN
32830 44 7d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79  D}.**.** Some sy
32840 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e 64 6f  stems (ex: windo
32850 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 68 65  ws95) do not the
32860 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 6c 65   operation imple
32870 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 71 6c  mented by.** sql
32880 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
32890 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
328a0 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
328b0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a 2a 2a  ex_try() will.**
328c0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
328d0 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 46 31  QLITE_BUSY.  {F1
328e0 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65  7030} The SQLite
328f0 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20   core only ever 
32900 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  uses.** sqlite3_
32910 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61  mutex_try() as a
32920 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73  n optimization s
32930 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74  o this is accept
32940 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 7b  able behavior. {
32950 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  END}.**.** {F170
32960 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  31} The sqlite3_
32970 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
32980 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
32990 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
329a0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
329b0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
329c0 68 72 65 61 64 2e 20 20 7b 55 31 37 30 33 32 7d  hread.  {U17032}
329d0 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   The behavior.**
329e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
329f0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
32a00 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
32a10 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
32a20 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
32a30 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
32a40 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 46 31   allocated.  {F1
32a50 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  7033} SQLite wil
32a60 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
32a70 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ther. {END}.**.*
32a80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
32a90 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
32aa0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32ab0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
32ac0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
32ad0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
32ae0 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
32af0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
32b00 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
32b10 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
32b20 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
32b30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
32b40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
32b50 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
32b60 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
32b70 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
32b80 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
32b90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32ba0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 63 61  F: Mutex Verifca
32bb0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 46  tion Routines {F
32bc0 31 37 30 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17080}.**.** The
32bd0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
32be0 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65  eld() and sqlite
32bf0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
32c00 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  ) routines.** ar
32c10 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
32c20 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74  se inside assert
32c30 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b  () statements. {
32c40 46 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69  F17081} The SQLi
32c50 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72  te core.** never
32c60 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
32c70 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69  ines except insi
32c80 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61  de an assert() a
32c90 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  nd applications.
32ca0 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74  ** are advised t
32cb0 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61  o follow the lea
32cc0 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20  d of the core.  
32cd0 7b 46 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72  {F17082} The cor
32ce0 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
32cf0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
32d00 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
32d10 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
32d20 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
32d30 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
32d40 55 47 20 66 6c 61 67 2e 20 20 7b 55 31 37 30 38  UG flag.  {U1708
32d50 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65  7} External mute
32d60 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
32d70 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65  s.** are only re
32d80 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64  quired to provid
32d90 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
32da0 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47   if SQLITE_DEBUG
32db0 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61   is.** defined a
32dc0 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20  nd if NDEBUG is 
32dd0 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  not defined..**.
32de0 2a 2a 20 7b 46 31 37 30 38 33 7d 20 54 68 65 73  ** {F17083} Thes
32df0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
32e00 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
32e10 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
32e20 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
32e30 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
32e40 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
32e50 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
32e60 67 20 74 68 72 65 61 64 2e 20 7b 45 4e 44 7d 0a  g thread. {END}.
32e70 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54  **.** {X17084} T
32e80 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32e90 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
32ea0 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
32eb0 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
32ec0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
32ed0 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a   actually work..
32ee0 2a 2a 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  ** If the implem
32ef0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
32f00 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
32f10 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
32f20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
32f30 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
32f40 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
32f50 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 79 73  s.** that always
32f60 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
32f70 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
32f80 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 0a 2a  t get spurious.*
32f90 2a 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c  * assertion fail
32fa0 75 72 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ures. {END}.**.*
32fb0 2a 20 7b 46 31 37 30 38 35 7d 20 49 66 20 74 68  * {F17085} If th
32fc0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
32fd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
32fe0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
32ff0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
33000 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
33010 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d  return 1.  {END}
33020 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
33030 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
33040 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
33050 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
33060 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
33070 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
33080 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
33090 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
330a0 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
330b0 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
330c0 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
330d0 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
330e0 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
330f0 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
33100 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
33110 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
33120 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
33130 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
33140 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
33150 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
33160 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 46  thing to do.  {F
33170 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74  17086} The sqlit
33180 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
33190 28 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  () .** interface
331a0 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
331b0 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
331c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
331d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
331e0 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
331f0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
33200 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
33210 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
33220 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
33230 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
33240 70 65 73 20 7b 46 31 37 30 30 31 7d 0a 2a 2a 0a  pes {F17001}.**.
33250 2a 2a 20 7b 46 31 37 30 30 32 7d 20 54 68 65 20  ** {F17002} The 
33260 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
33270 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
33280 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
33290 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
332a0 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
332b0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
332c0 61 6e 74 73 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 23  ants. {END}.*/.#
332d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
332e0 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
332f0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
33300 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
33310 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
33320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
33330 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
33340 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
33350 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
33360 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
33370 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
33380 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
33390 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
333a0 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
333b0 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  /* sqlite3_relea
333c0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23  se_memory() */.#
333d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
333e0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20  TEX_STATIC_PRNG 
333f0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
33400 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23  e3_random() */.#
33410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
33420 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20  TEX_STATIC_LRU  
33430 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70       6  /* lru p
33440 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a  age list */../*.
33450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77  ** CAPI3REF: Low
33460 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f  -Level Control O
33470 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  f Database Files
33480 20 7b 46 31 31 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F11300}.**.** 
33490 7b 46 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71  {F11301} The [sq
334a0 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
334b0 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ol()] interface 
334c0 6d 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63  makes a direct c
334d0 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46  all to the.** xF
334e0 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
334f0 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
33500 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
33510 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
33520 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69  .** with a parti
33530 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69  cular database i
33540 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
33550 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33560 2e 20 7b 46 31 31 33 30 32 7d 20 54 68 65 0a 2a  . {F11302} The.*
33570 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * name of the da
33580 74 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61  tabase is the na
33590 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74  me assigned to t
335a0 68 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74  he database by t
335b0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c  he.** <a href="l
335c0 61 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22  ang_attach.html"
335d0 3e 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20  >ATTACH</a> SQL 
335e0 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65  command that ope
335f0 6e 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ned the.** datab
33600 61 73 65 2e 20 7b 46 31 31 33 30 33 7d 20 54 6f  ase. {F11303} To
33610 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69   control the mai
33620 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
33630 20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d   use the name "m
33640 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c  ain".** or a NUL
33650 4c 20 70 6f 69 6e 74 65 72 2e 20 7b 46 31 31 33  L pointer. {F113
33660 30 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e  04} The third an
33670 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
33680 65 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ers to this rout
33690 69 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  ine.** are passe
336a0 64 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75  d directly throu
336b0 67 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64  gh to the second
336c0 20 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d   and third param
336d0 65 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20  eters of.** the 
336e0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
336f0 68 6f 64 2e 20 20 7b 46 31 31 33 30 35 7d 20 54  hod.  {F11305} T
33700 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
33710 6f 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  of the xFileCont
33720 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65  rol.** method be
33730 63 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e  comes the return
33740 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
33750 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  outine..**.** {F
33760 31 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65  11306} If the se
33770 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
33780 7a 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f  zDbName) does no
33790 74 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65  t match the name
337a0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20   of any.** open 
337b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
337c0 68 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  hen SQLITE_ERROR
337d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 46   is returned. {F
337e0 31 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f  11307} This erro
337f0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74  r.** code is not
33800 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20   remembered and 
33810 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61  will not be reca
33820 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  lled by [sqlite3
33830 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f  _errcode()].** o
33840 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
33850 67 28 29 5d 2e 20 7b 55 31 31 33 30 38 7d 20 54  g()]. {U11308} T
33860 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46  he underlying xF
33870 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
33880 64 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20  d might.** also 
33890 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52  return SQLITE_ER
338a0 52 4f 52 2e 20 20 7b 55 31 31 33 30 39 7d 20 54  ROR.  {U11309} T
338b0 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74  here is no way t
338c0 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65  o distinguish be
338d0 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f  tween.** an inco
338e0 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e  rrect zDbName an
338f0 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  d an SQLITE_ERRO
33900 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68  R return from th
33910 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20  e underlying.** 
33920 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
33930 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  hod. {END}.**.**
33940 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
33950 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
33960 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  TE].*/.int sqlit
33970 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
33980 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
33990 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69  char *zDbName, i
339a0 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt op, void*);..
339b0 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68  /*.** Undo the h
339c0 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74  ack that convert
339d0 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
339e0 20 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65   types to intege
339f0 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20  r for.** builds 
33a00 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69  on processors wi
33a10 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70  thout floating p
33a20 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f  oint support..*/
33a30 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
33a40 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
33a50 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c  NT.# undef doubl
33a60 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  e.#endif..#ifdef
33a70 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20   __cplusplus.}  
33a80 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65  /* End of the 'e
33a90 78 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b  xtern "C"' block
33aa0 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
33ab0 66 0a                                            f.