/ Hex Artifact Content
Login

Artifact 14ad9ebfa35f3682d6e96af5d9d7d8fee9ce700c:


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 37 39 20 32 30 30 38 2f  in,v 1.279 2008/
05f0: 30 31 2f 33 30 20 31 36 3a 31 36 3a 31 34 20 64  01/30 16:16:14 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 33 7d 20 54 68 65 20 5b 73 71  {F12373} 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 2f 0a 63 6f 6e 73 74 20  OMEM]..*/.const 
21ef0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21f00 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
21f10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21f20 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
21f30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
21f40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
21f50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
21f60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
21f70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21f80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
21f90 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
21fa0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
21fb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
21fc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
21fd0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
21fe0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
21ff0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
22000 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
22010 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
22020 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22030 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
22040 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
22050 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
22060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
22070 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
22080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22090 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
220a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
220b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
220c0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
220d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
220e0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
220f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22100 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
22110 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
22120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22130 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
22140 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
22150 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a  ject {F13300}.**
22160 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22170 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
22180 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
22190 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70   delete a .** [p
221a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
221b0 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65  t]. If the state
221c0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63  ment was.** exec
221d0 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
221e0 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  y, or not execut
221f0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20  ed at all, then 
22200 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
22210 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65  urned..** If exe
22220 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
22230 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
22240 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  hen an .** [erro
22250 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
22260 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22270 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
22280 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
22290 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
222a0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
222b0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
222c0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
222d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
222e0 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72  nt].  If the vir
222f0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73  tual machine has
22300 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74   not .** complet
22310 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
22320 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
22330 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
22340 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
22350 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
22360 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e  or an interrupt.
22370 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f    (See [sqlite3_
22380 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a  interrupt()].) .
22390 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
223a0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
223b0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
223c0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
223d0 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64  led,  .** depend
223e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
223f0 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
22400 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  e .** [error cod
22410 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
22420 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
22430 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
22440 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ANTS:.**.** {F11
22450 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
22460 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
22470 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
22480 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22490 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
224a0 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
224b0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
224c0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
224d0 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
224e0 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
224f0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ect..**.** {F113
22500 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
22510 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
22520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
22530 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
22540 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22550 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
22560 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
22570 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
22580 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22590 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
225a0 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
225b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
225c0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
225d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
225e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
225f0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
22600 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
22610 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13330}.**.** T
22620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
22630 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22640 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
22650 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
22660 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
22670 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73  ..** back to its
22680 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
22690 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
226a0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
226b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
226c0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
226d0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
226e0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
226f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
22700 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
22710 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
22720 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
22730 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
22740 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
22750 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
22760 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
22770 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b  * {F11332} The [
22780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
22790 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
227a0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
227b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
227c0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
227d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
227e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
227f0 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49  **.** {F11334} I
22800 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
22810 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
22820 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
22830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22850 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
22860 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
22870 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
22880 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
22890 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
228a0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
228b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
228c0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
228d0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
228e0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
228f0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
22900 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68  * {F11336} If th
22910 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
22920 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
22930 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20  tep(S)] for.**  
22940 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
22950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
22960 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
22970 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
22980 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
22990 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
229a0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
229b0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
229c0 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b  * {F11338} The [
229d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
229e0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
229f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
22a00 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
22a10 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
22a20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
22a30 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61  dings] on [prepa
22a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22a50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22a60 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
22a70 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
22a90 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
22aa0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
22ab0 46 31 36 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16100}.**.** Th
22ac0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
22ad0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
22ae0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
22af0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
22b00 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72  gates.** or to r
22b10 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
22b20 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67  vior of existing
22b30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
22b40 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
22b50 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65  he.** difference
22b60 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68   only between th
22b70 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  e two is that th
22b80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22b90 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20  er, the.** name 
22ba0 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
22bb0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
22bc0 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
22bd0 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d in UTF-8 for.*
22be0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
22bf0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
22c00 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74  UTF-16 for sqlit
22c10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
22c20 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
22c30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22c40 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
22c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
22c60 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20  at holds the.** 
22c70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
22c80 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20  aggregate is to 
22c90 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64 65  be added or rede
22ca0 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67  fined. If a sing
22cb0 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
22cc0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
22cd0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
22ce0 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
22cf0 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  n SQL.** functio
22d00 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
22d10 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
22d20 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65  ndividually to e
22d30 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
22d40 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63  handle with whic
22d50 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75  h they will be u
22d60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
22d70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22d80 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22d90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
22da0 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a  to be created.**
22db0 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a   or redefined..*
22dc0 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * The length of 
22dd0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
22de0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
22df0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
22e00 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  he .** zero-term
22e10 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
22e20 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
22e30 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
22e40 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
22e50 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
22e60 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
22e70 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
22e80 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
22e90 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
22ea0 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
22eb0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
22ec0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22ed0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
22ee0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
22ef0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
22f00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
22f10 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
22f20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
22f30 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
22f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
22f50 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
22f60 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
22f70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
22f80 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
22f90 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
22fa0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
22fb0 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  what .** [SQLITE
22fc0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
22fd0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
22fe0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
22ff0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
23000 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
23010 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
23020 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
23030 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
23040 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
23050 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
23060 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
23070 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
23080 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
23090 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
230a0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
230b0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
230c0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
230d0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
230e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
230f0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
23100 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
23110 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
23120 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
23130 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
23140 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
23150 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
23160 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
23170 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
23180 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
23190 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
231a0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
231b0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
231c0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
231d0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
231e0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
231f0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
23200 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
23210 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
23220 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
23230 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74  t care what.** t
23240 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
23250 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
23260 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
23270 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c  hould be.** [SQL
23280 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
23290 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
232a0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
232b0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
232c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
232d0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74  .** of the funct
232e0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
232f0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
23300 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ter using.** [sq
23310 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
23320 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
23330 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
23340 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
23350 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
23360 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
23370 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
23380 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
23390 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
233a0 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ent the SQL.** f
233b0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
233c0 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
233d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
233e0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
233f0 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  tation of.** the
23400 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20   xFunc callback 
23410 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
23420 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
23430 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
23440 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
23450 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
23460 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
23470 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
23480 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
23490 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64  .** of xStep and
234a0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
234b0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
234c0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
234d0 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69  delete an.** exi
234e0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
234f0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
23500 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
23510 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
23520 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  n.** callback..*
23530 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
23540 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
23550 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
23560 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
23570 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
23580 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
23590 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
235a0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
235b0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
235c0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
235d0 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74  ring perferred t
235e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
235f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
23600 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
23610 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
23620 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
23630 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
23640 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
23650 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20  is used..*/.int 
23660 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23670 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
23680 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
23690 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
236a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
236b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
236c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
236d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
236e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
236f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23700 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
23710 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
23720 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
23730 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
23740 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
23750 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
23760 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
23770 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
23780 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
23790 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
237a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
237b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
237c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
237d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
237e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
237f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
23800 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
23810 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
23820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
23830 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
23840 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
23850 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
23860 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
23870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
23880 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30  t Encodings {F10
23890 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  267}.**.** These
238a0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
238b0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
238c0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
238d0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
238e0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
238f0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
23900 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
23910 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
23920 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
23930 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
23940 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
23950 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
23960 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
23970 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
23980 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
23990 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
239a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
239b0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
239c0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
239d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
239e0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
239f0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
23a00 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
23a10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
23a20 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
23a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23a40 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69   Obsolete Functi
23a50 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
23a60 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  functions are al
23a70 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20  l now obsolete. 
23a80 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
23a90 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
23aa0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
23ab0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
23ac0 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f  , we continue to
23ad0 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73   support.** thes
23ae0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f  e functions.  Ho
23af0 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c  wever, new devel
23b00 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20  opment projects 
23b10 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
23b20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
23b30 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
23b40 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
23b50 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
23b60 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
23b70 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
23b80 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
23b90 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20  l you want they 
23ba0 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  do..*/.int sqlit
23bb0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
23bc0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
23bd0 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  xt*);.int sqlite
23be0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
23bf0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
23c00 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
23c10 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
23c20 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
23c30 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
23c40 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
23c50 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71  r(void);.void sq
23c60 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
23c70 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20  anup(void);.int 
23c80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
23c90 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
23ca0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
23cb0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
23cc0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
23cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
23ce0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
23cf0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
23d00 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a  lues {F15100}.**
23d10 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
23d20 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
23d30 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
23d40 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
23d50 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
23d60 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
23d70 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
23d80 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
23d90 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
23da0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
23db0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
23dc0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
23dd0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
23de0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
23df0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
23e00 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
23e10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
23e20 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
23e30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
23e40 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
23e50 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
23e60 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
23e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
23e80 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
23e90 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
23ea0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
23eb0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
23ec0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
23ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
23ee0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
23ef0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
23f00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
23f10 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
23f20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
23f30 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
23f40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
23f50 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
23f60 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
23f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
23f80 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
23f90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23fa0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
23fb0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
23fc0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
23fd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71  column_blob | sq
23fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72  lite3_column_* r
23ff0 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20  outines] except 
24000 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72  that .** these r
24010 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
24020 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76  ingle [sqlite3_v
24030 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69  alue*] pointer i
24040 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20  nstead.** of an 
24050 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
24060 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
24070 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
24080 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  mber..**.** The 
24090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
240a0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
240b0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 31   extracts a UTF1
240c0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
240d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
240e0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
240f0 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a   machine.  The.*
24100 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
24110 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
24120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24130 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
24140 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
24150 46 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  F16 strings as b
24160 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
24170 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
24180 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
24190 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
241a0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
241b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
241c0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
241d0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
241e0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
241f0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
24200 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
24210 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
24220 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
24230 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
24240 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
24250 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
24260 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
24270 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
24280 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
24290 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20   other.** words 
242a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
242b0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
242c0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
242d0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
242e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e  onversion is don
242f0 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  e.  Otherwise no
24300 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
24310 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51  rs.  The .** [SQ
24320 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
24330 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
24340 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
24350 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
24360 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
24370 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
24380 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
24390 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  e pointer that.*
243a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72  * is returned fr
243b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
243c0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
243d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
243e0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
243f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
24400 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
24410 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
24420 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
24430 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
24440 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
24450 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
24460 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
24470 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
24480 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
24490 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a  _text16()].  .**
244a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
244b0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
244c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
244d0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
244e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
244f0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
24500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70  sqlite3_value* p
24510 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72  arameters..** Or
24520 2c 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  , if the sqlite3
24530 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74  _value* argument
24540 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20   comes from the 
24550 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24560 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  value()].** inte
24570 72 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73  rface, then thes
24580 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
24590 64 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  d be called from
245a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
245b0 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71  .** that ran [sq
245c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
245d0 75 65 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63 6f 6e  ue()]..**.*/.con
245e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
245f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
24600 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
24610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
24620 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
24630 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
24640 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
24650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24660 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
24670 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
24680 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
24690 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
246a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
246b0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
246c0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
246d0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
246e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
246f0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
24700 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
24710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24720 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24730 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
24740 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
24750 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
24770 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
24780 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
24790 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
247a0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
247b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
247c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
247d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
247e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
247f0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
24800 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
24810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24820 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
24830 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
24840 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a  ntext {F16210}.*
24850 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
24860 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
24870 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
24880 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
24890 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
248a0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
248b0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
248c0 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 7b 46 31   state.  .** {F1
248d0 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20  6211} The first 
248e0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
248f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
24900 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  xt() routine is.
24910 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ** is called for
24920 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
24930 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20  gregate, SQLite 
24940 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73  allocates nBytes
24950 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65   of memory.** ze
24960 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ros that memory,
24970 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
24980 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a  ointer to it..**
24990 20 7b 46 31 36 32 31 32 7d 20 4f 6e 20 73 65 63   {F16212} On sec
249a0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
249b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  nt calls to sqli
249c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
249d0 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74  ntext().** for t
249e0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
249f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
24a00 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  , the same buffe
24a10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b  r is returned. {
24a20 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  END}.** The impl
24a30 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
24a40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63   the aggregate c
24a50 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72  an use the retur
24a60 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63  ned buffer to ac
24a70 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a  cumulate data..*
24a80 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 53 51  *.** {F16213} SQ
24a90 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
24aa0 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c  ly frees the all
24ab0 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68  ocated buffer wh
24ac0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
24ad0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  .** query conclu
24ae0 64 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  des. {END}.**.**
24af0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
24b00 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
24b10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
24b20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
24b30 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
24b40 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
24b50 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
24b60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
24b70 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
24b80 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
24b90 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
24ba0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
24bb0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
24bc0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
24bd0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
24be0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
24bf0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
24c00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
24c10 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
24c20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
24c30 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
24c40 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
24c50 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
24c60 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
24c70 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
24c80 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F16240}.**.** 
24c90 7b 46 31 36 32 34 31 7d 20 54 68 65 20 73 71 6c  {F16241} The sql
24ca0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
24cb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24cc0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
24cd0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
24ce0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
24cf0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
24d00 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
24d10 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b  .** of the the [
24d20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24d30 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
24d40 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
24d50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
24d60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
24d70 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
24d80 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
24d90 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
24da0 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
24db0 2a 0a 2a 2a 20 7b 55 31 36 32 34 33 7d 20 54 68  *.** {U16243} Th
24dc0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
24dd0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
24de0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
24df0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
24e00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
24e10 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
24e20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
24e30 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
24e40 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
24e50 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
24e60 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
24e70 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b  Auxiliary Data {
24e80 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16270}.**.** Th
24e90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
24ea0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
24eb0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
24ec0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
24ed0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
24ee0 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67  ta-data with arg
24ef0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
24f00 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
24f10 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
24f20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
24f30 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
24f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
24f50 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
24f60 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
24f70 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
24f80 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
24f90 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62   meta-data may b
24fa0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
24fb0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
24fc0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
24fd0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
24fe0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
24ff0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
25000 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
25010 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
25020 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
25030 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
25040 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61   as.** meta-data
25050 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25060 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
25070 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
25080 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
25090 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
250a0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
250b0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
250c0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
250d0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
250e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
250f0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
25100 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
25110 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
25120 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
25130 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
25140 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
25150 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ion..**.** {F162
25160 37 31 7d 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  71}.** The sqlit
25170 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
25180 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25190 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
251a0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a  the meta-data.**
251b0 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
251c0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
251d0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
251e0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
251f0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
25200 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
25210 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
25220 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32 37 32  tion..** {F16272
25230 7d 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74  } If no meta-dat
25240 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20  a has been ever 
25250 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
25260 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   Nth.** argument
25270 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
25280 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72  , or if the coor
25290 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
252a0 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
252b0 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
252c0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
252d0 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71  was set, then sq
252e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
252f0 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  a().** returns a
25300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
25310 2a 0a 2a 2a 20 7b 46 31 36 32 37 35 7d 20 54 68  *.** {F16275} Th
25320 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
25330 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
25340 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
25350 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  -data.** pointed
25360 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
25370 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
25380 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68  meta-data for th
25390 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
253a0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
253b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
253c0 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 53 75  nction. {END} Su
253d0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
253e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
253f0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
25400 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
25410 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
25420 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
25430 65 64 2e 20 0a 2a 2a 20 7b 46 31 36 32 37 37 7d  ed. .** {F16277}
25440 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
25450 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
25460 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
25470 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69  uctor .** functi
25480 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
25490 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
254a0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
254b0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
254c0 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20   meta-data when 
254d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
254e0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
254f0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
25500 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
25510 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
25520 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
25530 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44  omes first. {END
25540 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  }.**.** In pract
25550 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69  ice, meta-data i
25560 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
25570 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
25580 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
25590 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
255a0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
255b0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
255c0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
255d0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c  * values and SQL
255e0 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a   variables..**.*
255f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25600 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
25610 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
25620 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
25630 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25640 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
25650 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
25660 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
25670 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
25680 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
25690 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
256a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
256b0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
256c0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
256d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
256e0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
256f0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
25700 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
25710 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F10280}.**.** 
25720 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
25730 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
25740 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
25750 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
25760 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
25770 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
25780 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
25790 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
257a0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
257b0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
257c0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
257d0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
257e0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
257f0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
25800 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
25810 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
25820 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
25830 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
25840 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
25850 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
25860 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
25870 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
25880 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
25890 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
258a0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
258b0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
258c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
258d0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
258e0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
258f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
25900 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
25910 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
25920 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
25930 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
25940 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
25950 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
25960 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
25970 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
25980 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
25990 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
259a0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
259b0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
259c0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
259d0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
259e0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
259f0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
25a00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
25a10 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
25a20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
25a30 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a  on {F16400}.**.*
25a40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25a50 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
25a60 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
25a70 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
25a80 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
25a90 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
25aa0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
25ab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
25ac0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
25ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
25ae0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
25af0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
25b00 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
25b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
25b20 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
25b30 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a  much like the .*
25b40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25b50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
25b60 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66  ind_*] family of
25b70 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a   functions used.
25b80 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ** to bind value
25b90 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
25ba0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
25bb0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
25bc0 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  Refer to the.** 
25bd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25be0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
25bf0 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  d_* documentatio
25c00 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
25c10 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
25c20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 32 7d  ..**.** {F16402}
25c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
25c40 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
25c50 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
25c60 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
25c70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
25c80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
25c90 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
25ca0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
25cb0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
25cc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
25cd0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
25ce0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
25cf0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
25d00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
25d10 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65  .** {F16403} The
25d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
25d30 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66  zeroblob() inerf
25d40 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
25d50 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
25d60 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
25d70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
25d80 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
25d90 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
25da0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
25db0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
25dc0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
25dd0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
25de0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ter..**.** {F164
25df0 30 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  07} The sqlite3_
25e00 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
25e10 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
25e20 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
25e30 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
25e40 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
25e50 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
25e60 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
25e70 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
25e80 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
25e90 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20  .**.** {F16409} 
25ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
25eb0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
25ec0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
25ed0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
25ee0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
25ef0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
25f00 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
25f10 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
25f20 2a 20 7b 46 31 36 34 31 31 7d 20 53 51 4c 69 74  * {F16411} SQLit
25f30 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
25f40 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
25f50 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
25f60 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
25f70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
25f80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
25f90 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
25fa0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
25fb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 7b  error message. {
25fc0 46 31 36 34 31 32 7d 20 53 51 4c 69 74 65 20 69  F16412} SQLite i
25fd0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
25fe0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
25ff0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
26000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
26010 29 20 61 73 20 55 54 46 38 2e 20 20 7b 46 31 36  ) as UTF8.  {F16
26020 34 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 69  413} SQLite.** i
26030 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
26040 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
26050 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
26060 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
26070 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
26080 64 65 72 2e 20 20 7b 46 31 36 34 31 34 7d 20 49  der.  {F16414} I
26090 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
260a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
260b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
260c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
260d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
260e0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
260f0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
26100 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
26110 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
26120 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
26130 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
26140 72 2e 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 49  r..** {F16415} I
26150 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
26160 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26170 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
26180 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
26190 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
261a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
261b0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
261c0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
261d0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
261e0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
261f0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
26200 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
26210 2e 0a 2a 2a 20 7b 46 31 36 34 31 37 7d 20 54 68  ..** {F16417} Th
26220 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
26230 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
26240 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
26250 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
26260 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72  s make a copy pr
26270 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
26280 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
26290 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
262a0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 7b 45 4e  hey return.  {EN
262b0 44 7d 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  D} Hence, the ca
262c0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
262d0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
262e0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
262f0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
26300 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
26310 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32  rm..**.** {F1642
26320 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  1} The sqlite3_r
26330 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
26340 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
26350 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72  SQLite.** to thr
26360 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69  ow an error indi
26370 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
26380 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
26390 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65  to long.** to re
263a0 70 72 65 73 65 6e 74 2e 20 20 7b 46 31 36 34 32  present.  {F1642
263b0 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  2} The sqlite3_r
263c0 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
263d0 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65  terface.** cause
263e0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
263f0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  w an exception i
26400 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
26410 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  he a.** memory a
26420 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
26430 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 31 7d  ..**.** {F16431}
26440 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26450 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
26460 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
26470 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
26480 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26490 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
264a0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
264b0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
264c0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
264d0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
264e0 65 6e 74 2e 0a 2a 2a 20 7b 46 31 36 34 33 32 7d  ent..** {F16432}
264f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
26500 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
26510 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
26520 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
26530 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
26540 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26550 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
26560 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26570 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
26580 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
26590 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ument..**.** {F1
265a0 36 34 33 37 7d 20 54 68 65 20 73 71 6c 69 74 65  6437} The sqlite
265b0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
265c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
265d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
265e0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
265f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26600 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
26610 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 31  L..**.** {F16441
26620 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
26630 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
26640 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
26650 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65  16(), .** sqlite
26660 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
26670 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
26680 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
26690 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
266a0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
266b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
266c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
266d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
266e0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
266f0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
26700 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
26710 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
26720 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
26730 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
26740 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
26750 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
26760 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36 34 34  ively..** {F1644
26770 32 7d 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  2} SQLite takes 
26780 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
26790 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
267a0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
267b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
267c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
267d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
267e0 66 61 63 65 73 2e 0a 2a 2a 20 7b 46 31 36 34 34  faces..** {F1644
267f0 34 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61  4} If the 3rd pa
26800 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
26810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
26820 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
26830 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
26840 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
26850 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
26860 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
26870 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ter .** through 
26880 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
26890 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46 31  haracter..** {F1
268a0 36 34 34 37 7d 20 49 66 20 74 68 65 20 33 72 64  6447} If the 3rd
268b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
268c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
268d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
268e0 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
268f0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
26900 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
26910 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
26920 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
26930 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
26940 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
26950 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
26960 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
26970 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
26980 2e 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 49 66  ..** {F16451} If
26990 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
269a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
269b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
269c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
269d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
269e0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
269f0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
26a00 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
26a10 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
26a20 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
26a30 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  on the text or b
26a40 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20  lob result when 
26a50 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
26a60 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
26a70 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 33  sult..** {F16453
26a80 7d 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  } If the 4th par
26a90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
26aa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
26ab0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
26ac0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
26ad0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
26ae0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
26af0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
26b00 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73  hen.** SQLite as
26b10 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
26b20 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
26b30 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73  lt is constant s
26b40 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73  pace and.** does
26b50 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70   not copy the sp
26b60 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65  ace or call a de
26b70 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
26b80 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
26b90 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
26ba0 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20  lt..** {F16454} 
26bb0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
26bc0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
26bd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
26be0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
26bf0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
26c00 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
26c10 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
26c20 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
26c30 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
26c40 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
26c50 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
26c60 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
26c70 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
26c80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
26c90 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
26ca0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 31 7d 20 54  **.** {F16461} T
26cb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
26cc0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
26cd0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
26ce0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
26cf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26d00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
26d10 20 61 20 63 6f 70 79 20 74 68 65 20 5b 73 71 6c   a copy the [sql
26d20 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
26d30 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
26d40 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
26d50 65 74 65 72 2e 20 20 7b 46 31 36 34 36 33 7d 20  eter.  {F16463} 
26d60 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
26d70 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
26d80 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
26d90 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
26da0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
26db0 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  o that [sqlite3_
26dc0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
26dd0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
26de0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
26df0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
26e00 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
26e10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
26e20 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
26e30 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 34  arm..**.** {U164
26e40 39 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  91} These routin
26e50 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
26e60 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
26e70 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a  fferent thread .
26e80 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
26e90 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
26ea0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26eb0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
26ec0 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65   recieved.** the
26ed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
26ee0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
26ef0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
26f00 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
26f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
26f20 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
26f30 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
26f40 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
26f50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
26f60 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
26f70 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
26f80 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
26f90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
26fa0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
26fb0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
26fc0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
26fd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
26fe0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
26ff0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27000 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
27010 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
27020 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
27030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27040 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
27050 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
27060 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
27070 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
27080 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
27090 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
270a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
270b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
270c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
270d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
270e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
270f0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
27100 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
27110 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27120 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
27130 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
27140 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
27150 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
27160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27170 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
27180 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
27190 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
271a0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
271b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
271c0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
271d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
271e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
271f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
27200 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27210 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
27220 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
27230 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
27240 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
27250 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
27260 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
27270 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
27280 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
27290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
272a0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
272b0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
272c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
272d0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
272e0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
272f0 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F16600}.**.** 
27300 7b 46 31 36 36 30 31 7d 0a 2a 2a 20 54 68 65 73  {F16601}.** Thes
27310 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
27320 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
27330 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
27340 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  ces to the.** [s
27350 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
27360 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
27370 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
27380 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 32 7d   .**.** {F16602}
27390 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
273a0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
273b0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
273c0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
273d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
273e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
273f0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
27400 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
27410 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
27420 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
27430 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
27440 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
27450 6e 31 36 28 29 2e 20 7b 46 31 36 36 30 33 7d 20  n16(). {F16603} 
27460 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
27470 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
27480 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
27490 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
274a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  nt..**.** {F1660
274b0 34 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  4}.** The third 
274c0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
274d0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
274e0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
274f0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
27500 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
27510 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
27520 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
27530 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
27540 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
27550 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
27560 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
27570 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
27580 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
27590 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
275a0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
275b0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
275c0 79 2e 20 7b 46 31 36 36 30 35 7d 20 54 68 65 0a  y. {F16605} The.
275d0 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
275e0 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
275f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
27600 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
27610 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
27620 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
27630 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
27640 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
27650 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
27660 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
27670 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
27680 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
27690 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 37 7d  ..**.** {F16607}
276a0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
276b0 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69   the user suppli
276c0 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  ed routine must 
276d0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
276e0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65   fifth.** argume
276f0 6e 74 2e 20 7b 46 31 36 36 30 39 7d 20 49 66 20  nt. {F16609} If 
27700 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
27710 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
27720 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
27730 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
27740 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
27750 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
27760 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 7b  t anymore)..** {
27770 46 31 36 36 31 31 7d 20 45 61 63 68 20 74 69 6d  F16611} Each tim
27780 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
27790 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75  n.** supplied fu
277a0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
277b0 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20  d, it is passed 
277c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
277d0 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  id* passed as.**
277e0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
277f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27800 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27810 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
27820 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
27830 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72  n16() as its fir
27840 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
27850 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 0a 2a 2a 20  .** {F16612}.** 
27860 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
27870 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61  guments to the a
27880 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
27890 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
278a0 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
278b0 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
278c0 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64   by a (length, d
278d0 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e  ata) pair and en
278e0 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
278f0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
27900 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
27910 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
27920 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
27930 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
27940 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45  * registered. {E
27950 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74  ND} The applicat
27960 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
27970 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
27980 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
27990 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
279a0 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20   positive if.** 
279b0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
279c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
279d0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
279e0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
279f0 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69  ond.** string. i
27a00 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
27a10 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 7b  TRING2)..**.** {
27a20 46 31 36 36 31 35 7d 0a 2a 2a 20 54 68 65 20 73  F16615}.** The s
27a30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27a40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
27a50 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
27a60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27a70 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61  ().** excapt tha
27a80 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
27a90 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
27aa0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
27ab0 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
27ac0 6c 6c 61 74 69 6f 6e 2e 20 20 7b 46 31 36 36 31  llation.  {F1661
27ad0 37 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  7} The destructo
27ae0 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
27af0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
27b00 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
27b10 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
27b20 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
27b30 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
27b40 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
27b50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
27b60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
27b70 29 2e 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 20  )..** {F16618}  
27b80 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
27b90 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a  estroyed when.**
27ba0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
27bb0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
27bc0 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
27bd0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
27be0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68  nctions.** or wh
27bf0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  en the [sqlite3*
27c00 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
27c10 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  e is closed usin
27c20 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
27c30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
27c40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
27c50 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
27c60 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
27c70 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
27c80 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
27c90 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
27ca0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
27cb0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
27cc0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
27cd0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
27ce0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
27cf0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
27d00 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
27d10 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
27d20 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
27d30 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
27d40 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
27d50 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
27d60 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
27d70 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
27d80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
27d90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
27da0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
27db0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
27dc0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
27dd0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
27de0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
27df0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27e00 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
27e10 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
27e20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
27e30 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
27e40 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a  acks {F16700}.**
27e50 0a 2a 2a 20 7b 46 31 36 37 30 31 7d 0a 2a 2a 20  .** {F16701}.** 
27e60 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
27e70 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
27e80 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
27e90 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
27ea0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
27eb0 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
27ec0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
27ed0 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
27ee0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64  ed with the.** d
27ef0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
27f00 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  o be called when
27f10 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
27f20 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
27f30 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69  ence is.** requi
27f40 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  red..**.** {F167
27f50 30 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  02}.** If the fu
27f60 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
27f70 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
27f80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
27f90 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
27fa0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
27fb0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
27fc0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
27fd0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
27fe0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
27ff0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b  oded in UTF-8. {
28000 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74  F16703} If sqlit
28010 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
28020 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
28030 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72   the names.** ar
28040 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
28050 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
28060 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
28070 20 7b 46 31 36 37 30 34 7d 20 41 20 63 61 6c 6c   {F16704} A call
28080 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75   to either.** fu
28090 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
280a0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
280b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
280c0 36 37 30 35 7d 20 57 68 65 6e 20 74 68 65 20 63  6705} When the c
280d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
280e0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
280f0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
28100 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
28110 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28120 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
28130 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
28140 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
28150 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
28160 28 29 2e 20 7b 46 31 36 37 30 36 7d 20 54 68 65  (). {F16706} The
28170 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
28180 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
28190 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 7b 46 31  .** handle.  {F1
281a0 36 37 30 37 7d 20 54 68 65 20 74 68 69 72 64 20  6707} The third 
281b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
281c0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
281d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
281e0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
281f0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
28200 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a  cating the most.
28210 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  ** desirable for
28220 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
28230 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  on sequence func
28240 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a  tion required..*
28250 2a 20 7b 46 31 36 37 30 38 7d 20 54 68 65 20 66  * {F16708} The f
28260 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28270 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
28280 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
28290 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
282a0 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  e. {END}.**.** T
282b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
282c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
282d0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
282e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
282f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
28300 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
28310 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
28320 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
28330 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
28340 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
28350 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
28360 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
28370 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
28380 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
28390 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
283a0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
283b0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
283c0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
283d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
283e0 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
283f0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
28400 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
28410 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
28420 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
28430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
28440 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
28450 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
28460 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
28470 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
28480 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
28490 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
284a0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
284b0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
284c0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
284d0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
284e0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
284f0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
28500 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
28510 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
28520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
28540 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
28550 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
28560 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
28570 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
28580 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
28590 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
285a0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
285b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
285c0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
285d0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
285e0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
285f0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
28600 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
28610 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
28620 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
28630 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
28640 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
28650 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
28660 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
28670 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
28680 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
28690 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
286a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
286b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
286c0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
286d0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
286e0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
286f0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
28700 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
28710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28720 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63  F:  Suspend Exec
28730 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
28740 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a  t Time {F10530}.
28750 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 31 7d 20 54  **.** {F10531} T
28760 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
28770 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  () function.** c
28780 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
28790 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
287a0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
287b0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
287c0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
287d0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
287e0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
287f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 32  r..**.** {F10532
28800 7d 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  } If the operati
28810 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
28820 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
28830 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a   requests with .
28840 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
28850 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
28860 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
28870 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
28880 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72   to .** the near
28890 65 73 74 20 73 65 63 6f 6e 64 2e 20 7b 46 31 30  est second. {F10
288a0 35 33 33 7d 20 54 68 65 20 6e 75 6d 62 65 72 20  533} The number 
288b0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
288c0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
288d0 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  y .** requested 
288e0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
288f0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
28900 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  urned..**.** {F1
28910 30 35 33 34 7d 20 53 51 4c 69 74 65 20 69 6d 70  0534} SQLite imp
28920 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
28930 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
28940 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
28950 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
28960 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
28970 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45  _vfs] object. {E
28980 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ND}.*/.int sqlit
28990 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
289a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
289b0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
289c0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
289d0 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30  orary Files {F10
289e0 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  310}.**.** If th
289f0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
28a00 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
28a10 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
28a20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
28a30 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
28a40 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72   (a.ka. director
28a50 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
28a60 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
28a70 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
28a80 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
28a90 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
28aa0 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
28ab0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
28ac0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
28ad0 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
28ae0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
28af0 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
28b00 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
28b10 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
28b20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
28b30 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
28b40 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
28b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
28b60 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
28b70 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
28b80 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
28b90 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
28ba0 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
28bb0 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
28bc0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
28bd0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
28be0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
28bf0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
28c00 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
28c10 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
28c20 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
28c30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
28c40 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
28c50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28c60 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
28c70 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
28c80 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
28c90 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a  ode {F12930}.**.
28ca0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
28cb0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
28cc0 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
28cd0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
28ce0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
28cf0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
28d00 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
28d10 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
28d20 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
28d30 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f  ectively.   Auto
28d40 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
28d50 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e  n.** by default.
28d60 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
28d70 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
28d80 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
28d90 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
28da0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e  mit mode is reen
28db0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
28dc0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
28dd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
28de0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
28df0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
28e00 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
28e10 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
28e20 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
28e30 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  s (errors includ
28e40 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
28e50 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
28e60 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  ], .** [SQLITE_N
28e70 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
28e80 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
28e90 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
28ea0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
28eb0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
28ec0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
28ed0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
28ee0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
28ef0 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65  nd out if SQLite
28f00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
28f10 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
28f20 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
28f30 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
28f40 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
28f50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
28f60 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
28f70 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
28f80 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
28f90 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
28fa0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
28fb0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
28fc0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
28fd0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
28fe0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
28ff0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
29000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64  .**          mod
29010 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  e, respectively.
29020 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20  .**.** {F12932} 
29030 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
29040 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
29050 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d  ..**.** {F12933}
29060 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
29070 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
29080 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45  a successful [BE
29090 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
290a0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41  **.** {F12934} A
290b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
290c0 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73  s enabled by a s
290d0 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49  uccessful [COMMI
290e0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
290f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
29100 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a  tement..** .**.*
29110 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
29120 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49  **.** {U12936} I
29130 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
29140 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
29150 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
29160 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
29170 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65  *          conne
29180 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
29190 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
291a0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
291b0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20  turn value.**   
291c0 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69         is undefi
291d0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
291e0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
291f0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
29200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
29210 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
29220 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
29230 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29240 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F13120}.**.** 
29250 7b 46 31 33 31 32 31 7d 20 54 68 65 20 73 71 6c  {F13121} The sql
29260 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
29270 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
29280 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rns the [sqlite3
29290 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
292a0 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a  le to which a.**
292b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
292c0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
292d0 2a 20 7b 46 31 33 31 32 32 7d 20 74 68 65 20 64  * {F13122} the d
292e0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
292f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29300 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20  e3_db_handle.** 
29310 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
29320 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
29330 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73   was.** the firs
29340 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29350 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
29360 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
29370 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74  variants.** that
29380 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65   was used to cre
29390 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
293a0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
293b0 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  lace..*/.sqlite3
293c0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
293d0 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
293e0 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *);.../*.** CAPI
293f0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
29400 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
29410 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
29420 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12950}.**.** 
29430 7b 46 31 32 39 35 31 7d 20 54 68 65 20 73 71 6c  {F12951} The sql
29440 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
29450 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
29460 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
29470 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
29480 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
29490 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
294a0 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
294b0 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 41 6e 79  .** {F12952} Any
294c0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
294d0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
294e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
294f0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
29500 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
29510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
29520 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
29530 7b 46 31 32 39 35 33 7d 20 54 68 65 20 73 71 6c  {F12953} The sql
29540 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
29550 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
29560 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
29570 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
29580 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
29590 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
295a0 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65  tion is committe
295b0 64 2e 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 41  d..** {F12954} A
295c0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
295d0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
295e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
295f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
29600 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
29610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29620 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
29630 2a 20 7b 46 31 32 39 35 36 7d 20 54 68 65 20 70  * {F12956} The p
29640 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
29650 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
29660 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
29670 6b 2e 20 20 7b 46 31 32 39 35 37 7d 20 49 66 20  k.  {F12957} If 
29680 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
29690 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
296a0 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72  nction .** retur
296b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
296c0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
296d0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
296e0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
296f0 20 7b 46 31 32 39 35 38 7d 20 49 66 20 61 6e 6f   {F12958} If ano
29700 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
29710 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
29720 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
29730 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
29740 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
29750 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
29760 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ned..**.** {F129
29770 35 39 7d 20 52 65 67 69 73 74 65 72 69 6e 67 20  59} Registering 
29780 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
29790 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
297a0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
297b0 32 39 36 31 7d 20 46 6f 72 20 74 68 65 20 70 75  2961} For the pu
297c0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
297d0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
297e0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
297f0 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65  e been .** rolle
29800 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
29810 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
29820 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
29830 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
29840 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
29850 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
29860 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
29870 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 7b 46   to occur..** {F
29880 31 32 39 36 32 7d 20 54 68 65 20 72 6f 6c 6c 62  12962} The rollb
29890 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
298a0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
298b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
298c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
298d0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
298e0 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
298f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
29900 63 6c 6f 73 65 64 2e 0a 2a 2a 20 7b 46 31 32 39  closed..** {F129
29910 36 34 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  64} The rollback
29920 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
29930 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
29940 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
29950 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
29960 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c  use a commit cal
29970 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e  lback returned n
29980 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64  on-zero..** <tod
29990 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73  o> Check on this
299a0 20 3c 2f 74 6f 64 6f 3e 20 7b 45 4e 44 7d 0a 2a   </todo> {END}.*
299b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65  *.** These are e
299c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
299d0 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73  rfaces and are s
299e0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
299f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
29a00 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
29a10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
29a20 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
29a30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
29a40 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
29a50 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
29a60 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
29a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29a80 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
29a90 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
29aa0 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a  ks {F12970}.**.*
29ab0 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 73  * {F12971} The s
29ac0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
29ad0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ok() interface.*
29ae0 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  * registers a ca
29af0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
29b00 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
29b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
29b20 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ntified by the .
29b30 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
29b40 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  t to be invoked 
29b50 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
29b60 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
29b70 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
29b80 2a 2a 20 7b 46 31 32 39 37 32 7d 20 41 6e 79 20  ** {F12972} Any 
29b90 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
29ba0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
29bb0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
29bc0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a   for the same .*
29bd0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
29be0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
29bf0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  den..**.** {F129
29c00 37 34 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61  74} The second a
29c10 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
29c20 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
29c30 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
29c40 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73  hen a .** row is
29c50 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
29c60 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a  ed or deleted. .
29c70 2a 2a 20 7b 46 31 32 39 37 36 7d 20 54 68 65 20  ** {F12976} The 
29c80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
29c90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
29ca0 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
29cb0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
29cc0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
29cd0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 7b  ate_hook()..** {
29ce0 46 31 32 39 37 37 7d 20 54 68 65 20 73 65 63 6f  F12977} The seco
29cf0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  nd callback .** 
29d00 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
29d10 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
29d20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
29d30 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
29d40 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e  PDATE],.** depen
29d50 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
29d60 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
29d70 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
29d80 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
29d90 20 7b 46 31 32 39 37 38 7d 20 54 68 65 20 74 68   {F12978} The th
29da0 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72  ird and .** four
29db0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
29dc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
29dd0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
29de0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
29df0 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65  d .** table name
29e00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
29e10 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
29e20 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 66 69   {F12979} The fi
29e30 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
29e40 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68  ameter is .** th
29e50 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
29e60 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20  ow..** {F12981} 
29e70 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
29e80 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
29e90 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65  s the rowid afte
29ea0 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65  r .** the update
29eb0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
29ec0 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65  .** {F12983} The
29ed0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
29ee0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
29ef0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
29f00 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
29f10 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
29f20 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
29f30 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
29f40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 34 7d  ..**.** {F12984}
29f50 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
29f60 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
29f70 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
29f80 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
29f90 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
29fa0 7b 46 31 32 39 38 35 7d 20 4f 74 68 65 72 77 69  {F12985} Otherwi
29fb0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
29fc0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ned..*/.void *sq
29fd0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
29fe0 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
29ff0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
2a000 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
2a010 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
2a020 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
2a030 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
2a040 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
2a050 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
2a060 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
2a070 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10330}.**.**
2a080 20 7b 46 31 30 33 33 31 7d 0a 2a 2a 20 54 68 69   {F10331}.** Thi
2a090 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
2a0a0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
2a0b0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
2a0c0 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
2a0d0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
2a0e0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
2a0f0 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e  tween connection
2a100 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  s to the same da
2a110 74 61 62 61 73 65 2e 0a 2a 2a 20 7b 46 31 30 33  tabase..** {F103
2a120 33 32 7d 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69  32}.** Sharing i
2a130 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2a140 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2a150 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  e and disabled i
2a160 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  f the argument.*
2a170 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  * is false..**.*
2a180 2a 20 7b 46 31 30 33 33 33 7d 20 43 61 63 68 65  * {F10333} Cache
2a190 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
2a1a0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
2a1b0 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  .** for an entir
2a1c0 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d  e process. {END}
2a1d0 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67   This is a chang
2a1e0 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76  e as of SQLite v
2a1f0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a  ersion 3.5.0..**
2a200 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2a210 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68  ns of SQLite, sh
2a220 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61  aring was.** ena
2a230 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2a240 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2a250 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2a260 2a 2a 20 7b 46 31 30 33 33 34 7d 0a 2a 2a 20 54  ** {F10334}.** T
2a270 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
2a280 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
2a290 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
2a2a0 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
2a2b0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
2a2c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2a2d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2a2e0 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
2a2f0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
2a300 20 7b 46 31 30 33 33 35 7d 20 45 78 69 73 74 69   {F10335} Existi
2a310 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2a320 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2a330 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2a340 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2a350 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2a360 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2a370 65 20 6f 70 65 6e 65 64 2e 20 7b 45 4e 44 7d 0a  e opened. {END}.
2a380 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
2a390 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
2a3a0 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
2a3b0 64 20 63 61 63 68 65 2e 20 20 7b 46 31 30 33 33  d cache.  {F1033
2a3c0 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  6} When shared.*
2a3d0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
2a3e0 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
2a3f0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2a400 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
2a410 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
2a420 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
2a430 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
2a440 72 72 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  rror. {END}.**.*
2a450 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 69 73 20  * {F10337} This 
2a460 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a470 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
2a480 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a  hared cache was.
2a490 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
2a4a0 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
2a4b0 6c 6c 79 2e 20 20 7b 46 31 30 33 33 38 7d 20 41  lly.  {F10338} A
2a4c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  n [error code].*
2a4d0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  * is returned ot
2a4e0 68 65 72 77 69 73 65 2e 20 7b 45 4e 44 7d 0a 2a  herwise. {END}.*
2a4f0 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68  *.** {F10339} Sh
2a500 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2a510 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2a520 74 2e 20 7b 45 4e 44 7d 20 42 75 74 20 74 68 69  t. {END} But thi
2a530 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
2a540 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
2a550 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
2a560 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
2a570 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
2a580 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
2a590 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
2a5a0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
2a5b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
2a5c0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2a5d0 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
2a5e0 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d  CAPI3REF:  Attem
2a5f0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
2a600 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a  Memory {F17340}.
2a610 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54  **.** {F17341} T
2a620 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2a630 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2a640 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2a650 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65  o.** free N byte
2a660 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
2a670 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2a680 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2a690 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2a6a0 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65  ions held by the
2a6b0 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72   database labrar
2a6c0 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
2a6d0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68   used.** to cach
2a6e0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  e database pages
2a6f0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2a700 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2a710 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d  ample of.** non-
2a720 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2a730 2e 20 20 7b 46 31 36 33 34 32 7d 20 73 71 6c 69  .  {F16342} sqli
2a740 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2a750 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ry() returns.** 
2a760 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a770 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2a780 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
2a790 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
2a7a0 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ** than the amou
2a7b0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
2a7c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2a7d0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2a7e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a7f0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
2a800 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
2a810 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F17350}.**.** {
2a820 46 31 36 33 35 31 7d 20 54 68 65 20 73 71 6c 69  F16351} The sqli
2a830 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2a840 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mit() interface.
2a850 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ** places a "sof
2a860 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  t" limit on the 
2a870 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2a880 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2a890 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62  e allocated.** b
2a8a0 79 20 53 51 4c 69 74 65 2e 20 7b 46 31 36 33 35  y SQLite. {F1635
2a8b0 32 7d 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  2} If an interna
2a8c0 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
2a8d0 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68  requested .** th
2a8e0 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  at would exceed 
2a8f0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2a900 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
2a910 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
2a920 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e  is.** invoked on
2a930 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2a940 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
2a950 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
2a960 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
2a970 73 20 6d 61 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a  s made. {END}.**
2a980 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 54 68 65  .** {F16353} The
2a990 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2a9a0 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
2a9b0 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
2a9c0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2a9d0 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
2a9e0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
2a9f0 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
2aa00 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
2aa10 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
2aa20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
2aa30 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
2aa40 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
2aa50 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
2aa60 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  s..**.** {F16354
2aa70 7d 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  }.** A negative 
2aa80 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2aa90 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2aaa0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2aab0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2aac0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2aad0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2aae0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2aaf0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2ab00 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 7b 46  exhausted..** {F
2ab10 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75  16355} The defau
2ab20 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2ab30 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2ab40 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
2ab50 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
2ab60 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
2ab70 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
2ab80 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 7b 46  p limit.  .** {F
2ab90 31 36 33 35 36 7d 20 42 75 74 20 69 66 20 74 68  16356} But if th
2aba0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2abb0 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64  t cannot honored
2abc0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2abd0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2abe0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2abf0 74 69 66 69 63 61 74 69 6f 6e 2e 20 7b 45 4e 44  tification. {END
2ac00 7d 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74  }  This is why t
2ac10 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20  he limit is .** 
2ac20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20  called a "soft" 
2ac30 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64  limit.  It is ad
2ac40 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
2ac50 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
2ac60 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2ac70 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  , this routine o
2ac80 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20  nly constrained 
2ac90 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2aca0 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e  located by a sin
2acb0 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65  gle thread - the
2acc0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2acd0 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69  which this routi
2ace0 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67  ne.** runs.  Beg
2acf0 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
2ad00 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2ad10 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
2ad20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c  limit is.** appl
2ad30 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61  ied to all threa
2ad40 64 73 2e 20 7b 46 31 36 33 35 37 7d 20 54 68 65  ds. {F16357} The
2ad50 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2ad60 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2ad70 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2ad80 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2ad90 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2ada0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2adb0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
2adc0 4e 44 7d 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69  ND}  In.** versi
2add0 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69  on 3.5.0 there i
2ade0 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66  s no mechanism f
2adf0 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20  or limiting the 
2ae00 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a  heap usage for.*
2ae10 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72  * individual thr
2ae20 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  eads..*/.void sq
2ae30 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2ae40 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  limit(int);../*.
2ae50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78  ** CAPI3REF:  Ex
2ae60 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
2ae70 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
2ae80 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30   A Table {F12850
2ae90 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2aea0 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tine.** returns 
2aeb0 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20  meta-data about 
2aec0 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
2aed0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20  n of a specific 
2aee0 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
2aef0 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
2af00 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
2af10 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20  n handle passed 
2af20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
2af30 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65  ction .** argume
2af40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  nt..**.** The co
2af50 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
2af60 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
2af70 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
2af80 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
2af90 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69   .** this functi
2afa0 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
2afb0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
2afc0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
2afd0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
2afe0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
2aff0 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
2b000 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
2b010 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
2b020 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
2b030 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
2b040 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
2b050 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2b060 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
2b070 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
2b080 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
2b090 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65  algorithm as the
2b0a0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2b0b0 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73   uses to .** res
2b0c0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2b0d0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2b0e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
2b0f0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
2b100 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2b110 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
2b120 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
2b130 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  mn .** name of t
2b140 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2b150 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2b160 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2b170 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a  e parameters .**
2b180 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
2b190 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61  .** Meta informa
2b1a0 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  tion is returned
2b1b0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2b1c0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2b1d0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  ons passed as.**
2b1e0 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62   the 5th and sub
2b1f0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2b200 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2b210 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
2b220 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  e .** arguments 
2b230 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
2b240 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2b250 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2b260 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a  ment of meta .**
2b270 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2b280 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommitted..**.** 
2b290 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
2b2a0 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
2b2b0 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
2b2c0 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
2b2d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
2b2e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
2b2f0 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
2b300 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
2b310 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
2b320 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
2b330 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
2b340 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
2b350 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2b360 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
2b370 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
2b380 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
2b390 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
2b3a0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2b3b0 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
2b3c0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
2b3d0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
2b3e0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2b3f0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2b400 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
2b410 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
2b420 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
2b430 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
2b440 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
2b450 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
2b460 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
2b470 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
2b480 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
2b490 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
2b4a0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2b4b0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2b4c0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2b4d0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2b4e0 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
2b4f0 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
2b500 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2b510 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2b520 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2b530 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
2b540 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
2b550 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
2b560 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
2b570 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
2b580 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
2b590 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
2b5a0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2b5b0 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
2b5c0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
2b5d0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
2b5e0 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
2b5f0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
2b600 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
2b610 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
2b620 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
2b630 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
2b640 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
2b650 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
2b660 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
2b670 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
2b680 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
2b690 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
2b6a0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
2b6b0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
2b6c0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
2b6d0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
2b6e0 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
2b6f0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
2b700 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
2b710 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
2b720 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
2b730 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
2b740 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
2b750 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
2b760 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
2b770 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2b780 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
2b790 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
2b7a0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
2b7b0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
2b7c0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
2b7d0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
2b7e0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
2b7f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
2b800 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
2b810 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
2b820 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
2b830 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
2b840 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
2b850 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2b860 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2b870 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2b880 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2b890 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
2b8a0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
2b8b0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2b8c0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
2b8d0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
2b8e0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
2b8f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b910 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
2b920 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b930 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
2b940 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b950 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
2b960 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2b970 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
2b980 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
2b990 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b9a0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
2b9b0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
2b9c0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2b9d0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
2b9e0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
2b9f0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
2ba00 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2ba10 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
2ba20 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
2ba30 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
2ba40 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
2ba50 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
2ba60 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2ba70 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
2ba80 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
2ba90 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
2baa0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
2bab0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2bac0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
2bad0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
2bae0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
2baf0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2bb00 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
2bb10 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
2bb20 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
2bb30 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
2bb40 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
2bb50 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
2bb60 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
2bb70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2bb80 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
2bb90 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
2bba0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
2bbb0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
2bbc0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
2bbd0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
2bbe0 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
2bbf0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
2bc00 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
2bc10 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
2bc20 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
2bc30 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
2bc40 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
2bc50 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
2bc60 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
2bc70 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
2bc80 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2bc90 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
2bca0 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
2bcb0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2bcc0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2bcd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2bce0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2bcf0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
2bd00 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
2bd10 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
2bd20 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
2bd30 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
2bd40 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
2bd50 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
2bd60 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
2bd70 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
2bd80 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
2bd90 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
2bda0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
2bdb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2bdc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
2bdd0 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
2bde0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
2bdf0 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
2be00 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
2be10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2be20 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
2be30 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
2be40 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
2be50 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
2be60 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
2be70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2be80 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
2be90 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
2bea0 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
2beb0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
2bec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
2bed0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
2bee0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bef0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
2bf00 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
2bf10 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
2bf20 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
2bf30 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2bf40 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2bf50 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
2bf60 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
2bf70 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
2bf80 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
2bf90 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
2bfa0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
2bfb0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
2bfc0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
2bfd0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
2bfe0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
2bff0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
2c000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
2c010 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
2c020 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
2c030 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
2c040 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
2c050 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
2c060 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
2c070 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
2c080 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
2c090 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
2c0a0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
2c0b0 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
2c0c0 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
2c0d0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
2c0e0 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
2c0f0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
2c100 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
2c110 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
2c120 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
2c130 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
2c140 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
2c150 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
2c160 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
2c170 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
2c180 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
2c190 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
2c1a0 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
2c1b0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
2c1c0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2c1d0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
2c1e0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
2c1f0 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
2c200 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
2c210 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
2c220 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
2c230 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
2c240 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
2c250 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2c260 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
2c270 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
2c280 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
2c290 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
2c2a0 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
2c2b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2c2c0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
2c2d0 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
2c2e0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2c2f0 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
2c300 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
2c310 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
2c320 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
2c330 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65  invoked.** whene
2c340 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  ver a new databa
2c350 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c360 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
2c370 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2c380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2c390 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
2c3a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b  e3_open_v2()]. {
2c3b0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
2c3c0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
2c3d0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
2c3e0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
2c3f0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
2c400 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
2c410 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
2c420 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
2c430 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
2c440 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
2c450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2c460 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d  ..**.** {F12642}
2c470 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
2c480 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
2c490 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
2c4a0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
2c4b0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2c4c0 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
2c4d0 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
2c4e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d  ..**.** {F12643}
2c4f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
2c500 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
2c510 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
2c520 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
2c530 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
2c540 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c  from sqlite_mall
2c550 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79  oc(). {END} If y
2c560 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20  ou run a memory 
2c570 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20  leak.** checker 
2c580 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20  on your program 
2c590 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61  and it reports a
2c5a0 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66   leak because of
2c5b0 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20   this.** array, 
2c5c0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  then invoke [sql
2c5d0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
2c5e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2c5f0 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
2c600 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
2c610 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mory..**.** {F12
2c620 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
2c630 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2c640 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2c650 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
2c660 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
2c670 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
2c680 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
2c690 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
2c6a0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
2c6b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
2c6c0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2c6d0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2c6e0 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
2c6f0 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
2c700 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
2c710 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
2c720 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36  n Loading {F1266
2c730 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31  0}.**.** {F12661
2c740 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2c750 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
2c760 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2c770 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  ed.** automatic 
2c780 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
2c790 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  }  This.** routi
2c7a0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
2c7b0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
2c7c0 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d  r [sqlite3_autom
2c7d0 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29  atic_extension()
2c7e0 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
2c7f0 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69 73 20  * {F12662} This 
2c800 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
2c810 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2c820 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
2c830 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
2c840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
2c850 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
2c860 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
2c870 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
2c880 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
2c890 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2c8a0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
2c8b0 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
2c8c0 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
2c8d0 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
2c8e0 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
2c8f0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
2c900 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
2c910 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
2c920 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
2c930 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
2c940 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
2c950 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
2c960 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
2c970 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
2c980 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
2c990 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
2c9a0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
2c9b0 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
2c9c0 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
2c9d0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
2c9e0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
2c9f0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
2ca00 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
2ca10 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
2ca20 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  blizes, we will 
2ca30 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
2ca40 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
2ca50 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
2ca60 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
2ca70 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
2ca80 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
2ca90 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
2caa0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2cab0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
2cac0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2cad0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
2cae0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
2caf0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
2cb00 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
2cb10 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
2cb20 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2cb30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2cb40 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2cb50 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
2cb60 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
2cb70 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
2cb80 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64  le;../*.** A mod
2cb90 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f  ule is a class o
2cba0 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  f virtual tables
2cbb0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
2cbc0 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
2cbd0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
2cbe0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
2cbf0 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74  ucture.  This st
2cc00 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
2cc10 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  .** mostly of me
2cc20 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
2cc30 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  dule..*/.struct 
2cc40 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
2cc50 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
2cc60 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
2cc70 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
2cc80 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
2cc90 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
2cca0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
2ccb0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
2ccc0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
2ccd0 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
2cce0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
2ccf0 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
2cd00 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
2cd10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2cd20 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
2cd30 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
2cd40 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2cd50 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
2cd60 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
2cd70 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
2cd80 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
2cd90 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
2cda0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
2cdb0 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
2cdc0 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
2cdd0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2cde0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
2cdf0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2ce00 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
2ce10 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2ce20 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
2ce30 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
2ce40 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
2ce50 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
2ce60 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
2ce70 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
2ce80 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2ce90 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
2cea0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
2ceb0 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
2cec0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
2ced0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
2cee0 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
2cef0 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
2cf00 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
2cf10 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
2cf20 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
2cf30 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
2cf40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2cf50 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
2cf60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2cf70 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
2cf80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2cf90 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
2cfa0 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
2cfb0 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
2cfc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
2cfd0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
2cfe0 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
2cff0 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
2d000 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
2d010 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2d020 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
2d030 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d040 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
2d050 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
2d060 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2d070 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
2d080 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2d090 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
2d0a0 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
2d0b0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
2d0c0 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
2d0d0 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
2d0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d0f0 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
2d100 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2d110 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2d120 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
2d130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d140 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
2d150 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
2d160 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2d170 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
2d180 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
2d190 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d1a0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
2d1b0 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
2d1c0 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
2d1d0 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
2d1e0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
2d1f0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
2d200 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
2d210 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
2d220 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
2d230 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
2d240 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
2d250 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
2d260 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
2d270 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
2d280 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
2d290 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
2d2a0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
2d2b0 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
2d2c0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
2d2d0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
2d2e0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
2d2f0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
2d300 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
2d310 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
2d320 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
2d330 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
2d340 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
2d350 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
2d360 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20  &gt;=.  .** The 
2d370 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
2d380 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
2d390 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
2d3a0 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
2d3b0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2d3c0 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
2d3d0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
2d3e0 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
2d3f0 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
2d400 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
2d410 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
2d420 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
2d430 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
2d440 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
2d450 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
2d460 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
2d470 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
2d480 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
2d490 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
2d4a0 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
2d4b0 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
2d4c0 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
2d4d0 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
2d4e0 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
2d4f0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
2d500 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
2d510 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
2d520 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
2d530 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
2d540 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
2d550 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
2d560 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
2d570 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
2d580 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
2d590 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
2d5a0 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
2d5b0 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
2d5c0 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
2d5d0 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
2d5e0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
2d5f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2d600 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2d610 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
2d620 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
2d630 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
2d640 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
2d650 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
2d660 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
2d670 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
2d680 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
2d690 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
2d6a0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
2d6b0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
2d6c0 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
2d6d0 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
2d6e0 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
2d6f0 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
2d700 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
2d710 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2d720 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
2d730 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
2d740 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
2d750 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
2d760 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
2d770 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
2d780 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
2d790 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
2d7a0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
2d7b0 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
2d7c0 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
2d7d0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
2d7e0 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
2d7f0 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
2d800 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
2d810 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
2d820 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
2d830 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
2d840 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
2d850 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2d860 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
2d870 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
2d880 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
2d890 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
2d8a0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
2d8b0 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
2d8c0 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
2d8d0 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
2d8e0 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
2d8f0 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
2d900 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
2d910 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
2d920 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
2d930 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
2d940 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
2d950 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
2d960 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
2d970 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
2d980 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
2d990 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
2d9a0 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
2d9b0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
2d9c0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
2d9d0 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
2d9e0 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
2d9f0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
2da00 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
2da10 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
2da20 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
2da30 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
2da40 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2da50 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
2da60 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
2da70 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
2da80 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
2da90 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
2daa0 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
2dab0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2dac0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
2dad0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
2dae0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
2daf0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
2db00 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
2db10 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
2db20 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
2db30 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
2db40 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
2db50 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
2db60 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
2db70 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
2db80 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
2db90 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
2dba0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
2dbb0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
2dbc0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
2dbd0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
2dbe0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
2dbf0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
2dc00 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
2dc10 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
2dc20 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
2dc30 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
2dc40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
2dc50 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2dc60 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
2dc70 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
2dc80 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
2dc90 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
2dca0 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
2dcb0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
2dcc0 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
2dcd0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
2dce0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
2dcf0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
2dd00 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
2dd10 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
2dd20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2dd30 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
2dd40 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74  use */..  /* Out
2dd50 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
2dd60 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
2dd70 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
2dd80 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
2dd90 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
2dda0 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
2ddb0 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
2ddc0 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
2ddd0 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
2dde0 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
2ddf0 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
2de00 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
2de10 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
2de20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
2de30 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
2de40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de50 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
2de60 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
2de70 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
2de80 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
2de90 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
2dea0 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
2deb0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
2dec0 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
2ded0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
2dee0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
2def0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
2df00 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
2df10 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
2df20 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
2df30 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
2df40 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
2df50 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
2df60 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
2df70 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
2df80 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
2df90 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
2dfa0 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
2dfb0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2dfc0 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
2dfd0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2dfe0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
2dff0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2e000 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
2e010 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
2e020 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2e030 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
2e040 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
2e050 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
2e060 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
2e070 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2e080 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
2e090 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  CH 64../*.** Thi
2e0a0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  s routine is use
2e0b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
2e0c0 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  new module name 
2e0d0 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a  with an SQLite.*
2e0e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d  * connection.  M
2e0f0 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
2e100 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
2e110 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e  efore creating n
2e120 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  ew.** virtual ta
2e130 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75  bles on the modu
2e140 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73  le, or before us
2e150 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20  ing preexisting 
2e160 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
2e170 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  s of the module.
2e180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e190 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
2e1a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2e1b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
2e1c0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
2e1d0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
2e1e0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
2e1f0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2e200 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
2e210 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
2e220 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
2e230 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
2e240 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
2e250 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
2e260 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20  id *            
2e270 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
2e280 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
2e290 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
2e2a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  );../*.** This r
2e2b0 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69  outine is identi
2e2c0 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69 74  cal to the sqlit
2e2d0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
2e2e0 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  () method above,
2e2f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2e300 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
2e310 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
2e320 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
2e330 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
2e340 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
2e350 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
2e360 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
2e370 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74  bles API..*/.int
2e380 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e390 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
2e3a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2e3b0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
2e3c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
2e3d0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
2e3e0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
2e3f0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
2e400 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
2e410 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
2e420 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
2e430 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
2e440 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
2e450 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
2e460 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2e470 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
2e480 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
2e490 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
2e4a0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2e4b0 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
2e4c0 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
2e4d0 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
2e4e0 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  .** Every module
2e4f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e500 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
2e510 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
2e520 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
2e530 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
2e540 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20  icular instance 
2e550 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
2e560 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
2e570 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65  ll.** be tailore
2e580 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
2e590 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
2e5a0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
2e5b0 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70  tion.   The.** p
2e5c0 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
2e5d0 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
2e5e0 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
2e5f0 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20 63  ields that are c
2e600 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20  ommon.** to all 
2e610 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
2e620 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69  ations..**.** Vi
2e630 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
2e640 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
2e650 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
2e660 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
2e670 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
2e680 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
2e690 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d 73  intf() to zErrMs
2e6a0 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
2e6b0 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
2e6c0 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
2e6d0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
2e6e0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73  d by a call to s
2e6f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a  qlite3_free().**
2e700 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
2e710 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
2e720 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
2e730 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
2e740 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
2e750 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
2e760 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
2e770 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
2e780 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2e790 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
2e7a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
2e7b0 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
2e7c0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
2e7d0 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74  roed.  Note.** t
2e7e0 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  hat sqlite3_mpri
2e7f0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
2e800 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73 65  3_free() are use
2e810 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67  d on the zErrMsg
2e820 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20   field.** since 
2e830 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61  virtual tables a
2e840 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c  re commonly impl
2e850 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61  emented in loada
2e860 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77  ble extensions w
2e870 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68  hich.** do not h
2e880 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73 71  ave access to sq
2e890 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f  lite3MPrintf() o
2e8a0 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e  r sqlite3Free().
2e8b0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2e8c0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
2e8d0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2e8e0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
2e8f0 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
2e900 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
2e910 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
2e920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e930 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
2e940 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
2e950 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
2e960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e970 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
2e980 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
2e990 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
2e9a0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
2e9b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
2e9c0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
2e9d0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
2e9e0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79   */.};../* Every
2e9f0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
2ea00 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
2ea10 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
2ea20 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
2ea30 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
2ea40 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
2ea50 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72  int into the vir
2ea60 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61  tual table and a
2ea70 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
2ea80 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
2ea90 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
2eaa0 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
2eab0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
2eac0 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
2ead0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
2eae0 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
2eaf0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
2eb00 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
2eb10 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
2eb20 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
2eb30 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
2eb40 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
2eb50 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
2eb60 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
2eb70 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
2eb80 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
2eb90 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
2eba0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
2ebb0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
2ebc0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
2ebd0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2ebe0 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
2ebf0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
2ec00 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
2ec10 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
2ec20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ec30 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
2ec40 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
2ec50 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
2ec60 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20  .** The xCreate 
2ec70 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
2ec80 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65  hods of a module
2ec90 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
2eca0 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63  ng API.** to dec
2ecb0 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
2ecc0 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
2ecd0 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
2ece0 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
2ecf0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2ed00 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
2ed10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ed20 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
2ed30 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
2ed40 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65  ar *zCreateTable
2ed50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61  );../*.** Virtua
2ed60 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
2ed70 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
2ed80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2ed90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
2eda0 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64   using the xFind
2edb0 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e  Function method.
2edc0 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72    But global ver
2edd0 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
2ede0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
2edf0 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
2ee00 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
2ee10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
2ee20 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
2ee30 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
2ee40 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2ee50 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
2ee60 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
2ee70 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
2ee80 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
2ee90 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
2eea0 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
2eeb0 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
2eec0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
2eed0 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
2eee0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
2eef0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
2ef00 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
2ef10 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
2ef20 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
2ef30 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
2ef40 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
2ef50 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
2ef60 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
2ef70 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
2ef80 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
2ef90 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  -holder function
2efa0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
2efb0 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69  rloaded.** by vi
2efc0 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
2efd0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f  .** This API sho
2efe0 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65  uld be considere
2eff0 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69  d part of the vi
2f000 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
2f010 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20  rface,.** which 
2f020 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
2f030 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
2f040 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
2f050 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
2f060 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
2f070 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
2f080 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
2f090 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
2f0a0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2f0b0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2f0c0 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
2f0d0 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
2f0e0 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
2f0f0 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
2f100 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
2f110 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
2f120 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
2f130 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
2f140 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
2f150 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
2f160 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
2f170 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
2f180 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
2f190 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
2f1a0 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
2f1b0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
2f1c0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
2f1d0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
2f1e0 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
2f1f0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
2f200 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
2f210 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
2f220 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
2f230 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
2f240 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
2f250 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
2f260 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
2f270 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
2f280 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
2f290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f2a0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
2f2b0 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38   Open BLOB {F178
2f2c0 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00}.**.** An ins
2f2d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
2f2e0 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74  lowing opaque st
2f2f0 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64 20  ructure is used 
2f300 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  to .** represent
2f310 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e   an blob-handle.
2f320 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20    A blob-handle 
2f330 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a  is created by.**
2f340 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2f350 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72  pen()] and destr
2f360 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2f370 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
2f380 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2f390 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
2f3a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
2f3b0 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
2f3c0 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
2f3d0 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
2f3e0 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
2f3f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ions of the blob
2f400 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2f410 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
2f420 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f430 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
2f440 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74  e.** blob in byt
2f450 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
2f460 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
2f470 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
2f480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f490 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
2f4a0 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
2f4b0 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a  O {F17810}.**.**
2f4c0 20 7b 46 31 37 38 31 31 7d 20 54 68 69 73 20 69   {F17811} This i
2f4d0 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
2f4e0 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20  a handle to the 
2f4f0 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  blob located.** 
2f500 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
2f510 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
2f520 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
2f530 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
2f540 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
2f550 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
2f560 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
2f570 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
2f580 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
2f590 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
2f5a0 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
2f5b0 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
2f5c0 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
2f5d0 2a 0a 2a 2a 20 7b 46 31 37 38 31 32 7d 20 49 66  *.** {F17812} If
2f5e0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
2f5f0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
2f600 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70  , the blob is op
2f610 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61  ened for .** rea
2f620 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  d and write acce
2f630 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72  ss. If it is zer
2f640 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
2f650 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a  pened for read .
2f660 2a 2a 20 61 63 63 65 73 73 2e 20 7b 45 4e 44 7d  ** access. {END}
2f670 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d 20  .**.** {F17813} 
2f680 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
2f690 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
2f6a0 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
2f6b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2f6c0 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d  b | blob handle]
2f6d0 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a   is written to *
2f6e0 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 7b 46 31 37  ppBlob. .** {F17
2f6f0 38 31 34 7d 20 4f 74 68 65 72 77 69 73 65 20 61  814} Otherwise a
2f700 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  n error code is 
2f710 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a  returned and .**
2f720 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74   any value writt
2f730 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68  en to *ppBlob sh
2f740 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
2f750 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a   by the caller..
2f760 2a 2a 20 7b 46 31 37 38 31 35 7d 20 54 68 69 73  ** {F17815} This
2f770 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
2f780 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
2f790 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
2f7a0 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
2f7b0 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
2f7c0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2f7d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
2f7e0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3c 74 6f 64 6f  msg()]..** <todo
2f7f0 3e 57 65 20 73 68 6f 75 6c 64 20 67 6f 20 74 68  >We should go th
2f800 72 6f 75 67 68 20 61 6e 64 20 6d 61 72 6b 20 61  rough and mark a
2f810 6c 6c 20 69 6e 74 65 72 66 61 63 65 73 20 74 68  ll interfaces th
2f820 61 74 20 62 65 68 61 76 65 20 74 68 69 73 0a 2a  at behave this.*
2f830 2a 20 77 61 79 20 77 69 74 68 20 61 20 73 69 6d  * way with a sim
2f840 69 6c 61 72 20 73 74 61 74 65 6d 65 6e 74 3c 2f  ilar statement</
2f850 74 6f 64 6f 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  todo>.*/.int sql
2f860 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
2f870 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
2f880 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
2f890 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
2f8a0 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
2f8b0 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
2f8c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
2f8d0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
2f8e0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
2f8f0 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
2f900 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
2f910 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e A BLOB Handle 
2f920 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F17830}.**.** C
2f930 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
2f940 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
2f950 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  b handle]..**.**
2f960 20 7b 46 31 37 38 33 31 7d 20 43 6c 6f 73 69 6e   {F17831} Closin
2f970 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63  g a BLOB shall c
2f980 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74  ause the current
2f990 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
2f9a0 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65  commit.** if the
2f9b0 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
2f9c0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e  BLOBs, no pendin
2f9d0 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  g prepared state
2f9e0 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ments, and the.*
2f9f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2fa00 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f  ction is in auto
2fa10 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20  commit mode..** 
2fa20 7b 46 31 37 38 33 32 7d 20 49 66 20 61 6e 79 20  {F17832} If any 
2fa30 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
2fa40 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
2fa50 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
2fa60 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
2fa70 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
2fa80 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
2fa90 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a  ill fit. {END}.*
2faa0 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  * Closing the BL
2fab0 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
2fac0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
2fad0 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
2fae0 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
2faf0 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
2fb00 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
2fb10 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
2fb20 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
2fb30 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38  s closed.  {F178
2fb40 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74  33} Any errors t
2fb50 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
2fb60 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
2fb70 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
2fb80 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
2fb90 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  lue..**.** {F178
2fba0 33 39 7d 20 54 68 65 20 42 4c 4f 42 20 69 73 20  39} The BLOB is 
2fbb0 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
2fbc0 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
2fbd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2fbe0 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
2fbf0 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
2fc00 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
2fc10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2fc20 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
2fc30 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
2fc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
2fc50 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
2fc60 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b  f An Open BLOB {
2fc70 46 31 37 38 30 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F17805}.**.** {F
2fc80 31 36 38 30 36 7d 20 52 65 74 75 72 6e 20 74 68  16806} Return th
2fc90 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
2fca0 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65  of the blob acce
2fcb0 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f  ssible via the o
2fcc0 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
2fcd0 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
2fce0 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61  dle] passed as a
2fcf0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69  n argument..*/.i
2fd00 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
2fd10 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
2fd20 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
2fd30 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61  PI3REF:  Read Da
2fd40 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
2fd50 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31  ncrementally {F1
2fd60 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7850}.**.** This
2fd70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2fd80 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
2fd90 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  rom an open .** 
2fda0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
2fdb0 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74  blob-handle] int
2fdc0 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c  o a caller suppl
2fdd0 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 7b  ied buffer..** {
2fde0 46 31 37 38 35 31 7d 20 6e 20 62 79 74 65 73 20  F17851} n bytes 
2fdf0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
2fe00 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a  ed into buffer.*
2fe10 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  * z from the ope
2fe20 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67  n blob, starting
2fe30 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
2fe40 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35  et..**.** {F1785
2fe50 32 7d 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66  2} If offset iOf
2fe60 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
2fe70 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n n bytes from t
2fe80 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c  he end of the bl
2fe90 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ob, .** [SQLITE_
2fea0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
2feb0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
2fec0 73 20 72 65 61 64 2e 20 20 7b 46 31 37 38 35 33  s read.  {F17853
2fed0 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65 73  } If n is.** les
2fee0 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c  s than zero [SQL
2fef0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
2ff00 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
2ff10 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a  ta is read..**.*
2ff20 2a 20 7b 46 31 37 38 35 34 7d 20 4f 6e 20 73 75  * {F17854} On su
2ff30 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
2ff40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
2ff50 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
2ff60 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
2ff70 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
2ff80 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2ff90 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
2ffa0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
2ffb0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
2ffc0 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69  oid *z, int n, i
2ffd0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
2ffe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 57  .** CAPI3REF:  W
2fff0 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41  rite Data Into A
30000 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
30010 6c 6c 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a  lly {F17870}.**.
30020 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
30030 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74   is used to writ
30040 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f  e data into an o
30050 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
30060 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
30070 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72  dle] from a user
30080 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72   supplied buffer
30090 2e 0a 2a 2a 20 7b 46 31 37 38 37 31 7d 20 6e 20  ..** {F17871} n 
300a0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
300b0 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
300c0 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e  e buffer.** poin
300d0 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f  ted to by z into
300e0 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20   the open blob, 
300f0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
30100 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
30110 2a 20 7b 46 31 37 38 37 32 7d 20 49 66 20 74 68  * {F17872} If th
30120 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  e [sqlite3_blob 
30130 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70  | blob-handle] p
30140 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
30150 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  st argument.** w
30160 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
30170 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  r writing (the f
30180 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
30190 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
301a0 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20  open()].*** was 
301b0 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63  zero), this func
301c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
301d0 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
301e0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 33 7d 20 54  **.** {F17873} T
301f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
30200 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
30210 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
30220 20 62 6c 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20   blob; it is.** 
30230 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
30240 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
30250 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e  e of a blob usin
30260 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 7b  g this API..** {
30270 46 31 37 38 37 34 7d 20 49 66 20 6f 66 66 73 65  F17874} If offse
30280 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
30290 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66  s than n bytes f
302a0 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
302b0 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51  he blob, .** [SQ
302c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
302d0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
302e0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20  ata is written. 
302f0 20 7b 46 31 37 38 37 35 7d 20 49 66 20 6e 20 69   {F17875} If n i
30300 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
30310 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ero [SQLITE_ERRO
30320 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
30330 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
30340 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  itten..**.** {F1
30350 37 38 37 36 7d 20 4f 6e 20 73 75 63 63 65 73 73  7876} On success
30360 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
30370 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
30380 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  se, an .** [erro
30390 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
303a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
303b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
303c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
303d0 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74  blob_write(sqlit
303e0 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74  e3_blob *, const
303f0 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
30400 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
30410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30420 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79   Virtual File Sy
30430 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 46 31  stem Objects {F1
30440 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 76 69  1200}.**.** A vi
30450 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d  rtual filesystem
30460 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71   (VFS) is an [sq
30470 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
30480 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  t.** that SQLite
30490 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63   uses to interac
304a0 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e  t.** with the un
304b0 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
304c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74  ng system.  Most
304d0 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74   builds come wit
304e0 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65  h a.** single de
304f0 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69  fault VFS that i
30500 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
30510 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  r the host compu
30520 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ter..** New VFSe
30530 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
30540 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67  red and existing
30550 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e   VFSes can be un
30560 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54  registered..** T
30570 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74  he following int
30580 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
30590 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ided..**.** {F11
305a0 32 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  201} The sqlite3
305b0 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65  _vfs_find() inte
305c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
305d0 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 61  pointer to .** a
305e0 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e   VFS given its n
305f0 61 6d 65 2e 20 20 7b 46 31 31 32 30 32 7d 20 4e  ame.  {F11202} N
30600 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
30610 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 7b 46 31 31  nsitive..** {F11
30620 32 30 33 7d 20 4e 61 6d 65 73 20 61 72 65 20 7a  203} Names are z
30630 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
30640 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
30650 20 7b 46 31 31 32 30 34 7d 20 49 66 20 74 68 65   {F11204} If the
30660 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
30670 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
30680 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b  r is returned. {
30690 46 31 31 32 30 35 7d 20 49 66 20 7a 56 66 73 4e  F11205} If zVfsN
306a0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
306b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a   the default .**
306c0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
306d0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
306e0 31 31 32 31 30 7d 20 4e 65 77 20 56 46 53 65 73  11210} New VFSes
306f0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
30700 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73  with sqlite3_vfs
30710 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20  _register()..** 
30720 7b 46 31 31 32 31 31 7d 20 45 61 63 68 20 6e 65  {F11211} Each ne
30730 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
30740 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
30750 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
30760 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 7b 46  ag is set..** {F
30770 31 31 32 31 32 7d 20 54 68 65 20 73 61 6d 65 20  11212} The same 
30780 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 73  VFS can be regis
30790 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
307a0 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a  imes without inj
307b0 75 72 79 2e 0a 2a 2a 20 7b 46 31 31 32 31 33 7d  ury..** {F11213}
307c0 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73   To make an exis
307d0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
307e0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
307f0 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
30800 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
30810 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
30820 7b 55 31 31 32 31 34 7d 20 49 66 20 74 77 6f 20  {U11214} If two 
30830 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
30840 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
30850 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
30860 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
30870 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
30880 20 20 7b 55 31 31 32 31 35 7d 20 49 66 20 61 0a    {U11215} If a.
30890 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74  ** VFS is regist
308a0 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65  ered with a name
308b0 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72   that is NULL or
308c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
308d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
308e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
308f0 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  ned..** .** {F11
30900 32 32 30 7d 20 55 6e 72 65 67 69 73 74 65 72 20  220} Unregister 
30910 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73  a VFS with the s
30920 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
30930 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63  ister() interfac
30940 65 2e 0a 2a 2a 20 7b 46 31 31 32 32 31 7d 20 49  e..** {F11221} I
30950 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
30960 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
30970 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
30980 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
30990 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
309a0 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
309b0 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
309c0 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  rary..*/.sqlite3
309d0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
309e0 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
309f0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
30a00 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
30a10 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
30a20 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
30a30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
30a40 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
30a50 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
30a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
30a70 75 74 65 78 65 73 20 7b 46 31 37 30 30 30 7d 0a  utexes {F17000}.
30a80 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
30a90 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
30aa0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68   routines for th
30ab0 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e  read.** synchron
30ac0 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68  ization.  Though
30ad0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64   they are intend
30ae0 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  ed for internal.
30af0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
30b00 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b  , code that link
30b10 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
30b20 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64   is.** permitted
30b30 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74   to use any of t
30b40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
30b50 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
30b60 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74  source code cont
30b70 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ains multiple im
30b80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a  plementations .*
30b90 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
30ba0 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61   routines.  An a
30bb0 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
30bc0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
30bd0 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74  selected automat
30be0 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c  ically at compil
30bf0 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c  e-time.  The fol
30c00 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d  lowing.** implem
30c10 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76  entations are av
30c20 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53  ailable in the S
30c30 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a  QLite core:.**.*
30c40 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
30c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
30c60 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  2.** <li>   SQLI
30c70 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44  TE_MUTEX_PTHREAD
30c80 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
30c90 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c  E_MUTEX_W32.** <
30ca0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
30cb0 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e  EX_NOOP.** </ul>
30cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
30cd0 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70  E_MUTEX_NOOP imp
30ce0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
30cf0 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73   set of routines
30d00 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e   .** that does n
30d10 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61  o real locking a
30d20 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  nd is appropriat
30d30 65 20 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a  e for use in .**
30d40 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64   a single-thread
30d50 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  ed application. 
30d60 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
30d70 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45  X_OS2,.** SQLITE
30d80 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20  _MUTEX_PTHREAD, 
30d90 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
30da0 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74  _W32 implementat
30db0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72  ions.** are appr
30dc0 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
30dd0 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78 2c 20 61  on os/2, unix, a
30de0 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a  nd windows..** .
30df0 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  ** If SQLite is 
30e00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
30e10 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  e SQLITE_MUTEX_A
30e20 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73  PPDEF preprocess
30e30 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69  or.** macro defi
30e40 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c  ned (with "-DSQL
30e50 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
30e60 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75  =1"), then no mu
30e70 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
30e80 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65  ation is include
30e90 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
30ea0 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74 65  ry.  The.** mute
30eb0 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  x interface rout
30ec0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
30ed0 65 20 62 65 63 6f 6d 65 20 65 78 74 65 72 6e 61  e become externa
30ee0 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63 65 73 20  l.** references 
30ef0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  in the SQLite li
30f00 62 72 61 72 79 20 66 6f 72 20 77 68 69 63 68 20  brary for which 
30f10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
30f20 2a 2a 20 6d 75 73 74 20 62 65 20 70 72 6f 76 69  ** must be provi
30f30 64 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ded by the appli
30f40 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 66 61  cation.  This fa
30f50 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73 20 61 6e  cility allows an
30f60 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
30f70 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
30f80 73 74 20 53 51 4c 69 74 65 20 74 6f 20 70 72 6f  st SQLite to pro
30f90 76 69 64 65 20 69 74 73 20 6f 77 6e 20 6d 75 74  vide its own mut
30fa0 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
30fb0 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 68 61 76  tion without hav
30fc0 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  ing to modify th
30fd0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a 2a  e SQLite core..*
30fe0 2a 0a 2a 2a 20 7b 46 31 37 30 31 31 7d 20 54 68  *.** {F17011} Th
30ff0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
31000 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
31010 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
31020 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
31030 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
31040 6f 20 69 74 2e 20 7b 46 31 37 30 31 32 7d 20 49  o it. {F17012} I
31050 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
31060 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
31070 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
31080 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
31090 74 65 64 2e 20 7b 46 31 37 30 31 33 7d 20 53 51  ted. {F17013} SQ
310a0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
310b0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
310c0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
310d0 72 2e 20 7b 46 31 37 30 31 34 7d 20 54 68 65 20  r. {F17014} The 
310e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
310f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
31100 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
31110 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
31120 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
31130 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
31140 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
31150 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
31160 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
31170 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
31180 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
31190 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
311a0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
311b0 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
311c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
311d0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
311e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
311f0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
31200 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
31210 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f 75 6c 3e  TIC_LRU.** </ul>
31220 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
31230 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20  7015} The first 
31240 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  two constants ca
31250 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
31260 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
31270 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
31280 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74  ex.  The new mut
31290 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20  ex is recursive 
312a0 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
312b0 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69  X_RECURSIVE.** i
312c0 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e  s used but not n
312d0 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68  ecessarily so wh
312e0 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
312f0 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45  FAST is used. {E
31300 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ND}.** The mutex
31310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31320 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
31330 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
31340 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
31350 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
31360 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
31370 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
31380 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
31390 6e 74 20 74 6f 2e 20 20 7b 46 31 37 30 31 36 7d  nt to.  {F17016}
313a0 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c   But SQLite will
313b0 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20   only request a 
313c0 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20  recursive mutex 
313d0 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72  in.** cases wher
313e0 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64  e it really need
313f0 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66  s one.  {END} If
31400 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
31410 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
31420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31430 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
31440 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
31450 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
31460 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
31470 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
31480 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
31490 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
314a0 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  FAST..**.** {F17
314b0 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61  017} The other a
314c0 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
314d0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
314e0 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20  ex_alloc() each 
314f0 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
31500 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
31510 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
31520 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73  x. {END}  Four s
31530 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
31540 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
31550 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
31560 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
31570 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
31580 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
31590 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
315a0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
315b0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
315c0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
315d0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
315e0 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
315f0 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
31600 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
31610 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
31620 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
31630 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
31640 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
31650 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
31660 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
31670 0a 2a 2a 20 7b 46 31 37 30 31 38 7d 20 4e 6f 74  .** {F17018} Not
31680 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
31690 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
316a0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
316b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
316c0 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
316d0 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
316e0 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
316f0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
31700 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
31710 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
31720 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b  n every call.  {
31730 46 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20  F17034} But for 
31740 74 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d  the static .** m
31750 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20  utex types, the 
31760 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65  same mutex is re
31770 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20  turned on every 
31780 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a  call that has.**
31790 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e   the same type n
317a0 75 6d 62 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  umber. {END}.**.
317b0 2a 2a 20 7b 46 31 37 30 31 39 7d 20 54 68 65 20  ** {F17019} The 
317c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
317d0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
317e0 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
317f0 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
31800 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
31810 2e 20 7b 46 31 37 30 32 30 7d 20 53 51 4c 69 74  . {F17020} SQLit
31820 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
31830 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
31840 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  .** dynamic mute
31850 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61  x that it alloca
31860 74 65 73 2e 20 7b 55 31 37 30 32 31 7d 20 54 68  tes. {U17021} Th
31870 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
31880 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e  s must not be in
31890 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68   .** use when th
318a0 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  ey are deallocat
318b0 65 64 2e 20 7b 55 31 37 30 32 32 7d 20 41 74 74  ed. {U17022} Att
318c0 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c  empting to deall
318d0 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a  ocate a static.*
318e0 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20  * mutex results 
318f0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31900 61 76 69 6f 72 2e 20 7b 46 31 37 30 32 33 7d 20  avior. {F17023} 
31910 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61  SQLite never dea
31920 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74  llocates.** a st
31930 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44  atic mutex. {END
31940 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
31950 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
31960 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  ) and sqlite3_mu
31970 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e  tex_try() routin
31980 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f  es attempt.** to
31990 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20   enter a mutex. 
319a0 7b 46 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74  {F17024} If anot
319b0 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c  her thread is al
319c0 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65  ready within the
319d0 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74   mutex,.** sqlit
319e0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
319f0 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20   will block and 
31a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
31a10 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  y() will return.
31a20 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ** SQLITE_BUSY. 
31a30 7b 46 31 37 30 32 35 7d 20 20 54 68 65 20 73 71  {F17025}  The sq
31a40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
31a50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
31a60 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  rns SQLITE_OK.**
31a70 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
31a80 20 65 6e 74 72 79 2e 20 20 7b 46 31 37 30 32 36   entry.  {F17026
31a90 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65  } Mutexes create
31aa0 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  d using.** SQLIT
31ab0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
31ac0 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64  E can be entered
31ad0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
31ae0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
31af0 61 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 37 7d 20  ad..** {F17027} 
31b00 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68  In such cases th
31b10 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74  e,.** mutex must
31b20 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71   be exited an eq
31b30 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  ual number of ti
31b40 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68  mes before anoth
31b50 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e  er thread.** can
31b60 20 65 6e 74 65 72 2e 20 20 7b 55 31 37 30 32 38   enter.  {U17028
31b70 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  } If the same th
31b80 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
31b90 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
31ba0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
31bb0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
31bc0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
31bd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 46 31  ndefined..** {F1
31be0 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  7029} SQLite wil
31bf0 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a  l never exhibit.
31c00 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72  ** such behavior
31c10 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20   in its own use 
31c20 6f 66 20 6d 75 74 65 78 65 73 2e 20 7b 45 4e 44  of mutexes. {END
31c30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73  }.**.** Some sys
31c40 74 65 6d 73 20 28 65 78 3a 20 77 69 6e 64 6f 77  tems (ex: window
31c50 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 68 65 20  s95) do not the 
31c60 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 6c 65 6d  operation implem
31c70 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69  ented by.** sqli
31c80 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e  te3_mutex_try().
31c90 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65    On those syste
31ca0 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ms, sqlite3_mute
31cb0 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a 2a 2a 20  x_try() will.** 
31cc0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51  always return SQ
31cd0 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 46 31 37  LITE_BUSY.  {F17
31ce0 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20  030} The SQLite 
31cf0 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
31d00 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
31d10 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
31d20 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
31d30 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
31d40 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 7b 45  ble behavior. {E
31d50 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 33  ND}.**.** {F1703
31d60 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
31d70 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
31d80 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
31d90 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
31da0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
31db0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
31dc0 72 65 61 64 2e 20 20 7b 55 31 37 30 33 32 7d 20  read.  {U17032} 
31dd0 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
31de0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
31df0 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
31e00 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
31e10 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ed by the.** cal
31e20 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69  ling thread or i
31e30 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
31e40 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 46 31 37  allocated.  {F17
31e50 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  033} SQLite will
31e60 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
31e70 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  her. {END}.**.**
31e80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
31e90 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
31ea0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
31eb0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
31ec0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
31ed0 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
31ee0 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
31ef0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
31f00 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
31f10 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
31f20 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
31f30 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
31f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
31f50 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
31f60 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
31f70 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
31f80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
31f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31fa0 3a 20 4d 75 74 65 78 20 56 65 72 69 66 63 61 74  : Mutex Verifcat
31fb0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 46 31  ion Routines {F1
31fc0 37 30 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7080}.**.** The 
31fd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
31fe0 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ld() and sqlite3
31ff0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
32000 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
32010 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
32020 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28  e inside assert(
32030 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 46  ) statements. {F
32040 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74  17081} The SQLit
32050 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
32060 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
32070 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
32080 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
32090 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
320a0 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
320b0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
320c0 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b   of the core.  {
320d0 46 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65  F17082} The core
320e0 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65   only.** provide
320f0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
32100 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  s for these rout
32110 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20  ines when it is 
32120 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
32130 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55   the SQLITE_DEBU
32140 47 20 66 6c 61 67 2e 20 20 7b 55 31 37 30 38 37  G flag.  {U17087
32150 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78  } External mutex
32160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32170 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
32180 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
32190 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
321a0 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
321b0 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
321c0 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
321d0 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
321e0 2a 20 7b 46 31 37 30 38 33 7d 20 54 68 65 73 65  * {F17083} These
321f0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
32200 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20   return true if 
32210 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65  the mutex in the
32220 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  ir argument.** i
32230 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65  s held or not he
32240 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  ld, respectively
32250 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67  , by the calling
32260 20 74 68 72 65 61 64 2e 20 7b 45 4e 44 7d 0a 2a   thread. {END}.*
32270 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68  *.** {X17084} Th
32280 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32290 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
322a0 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72   to provided ver
322b0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a  sions of these.*
322c0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
322d0 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a  actually work..*
322e0 2a 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  * If the impleme
322f0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
32300 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
32310 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
32320 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
32330 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
32340 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
32350 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 79 73 20  .** that always 
32360 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
32370 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
32380 20 67 65 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a   get spurious.**
32390 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75   assertion failu
323a0 72 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  res. {END}.**.**
323b0 20 7b 46 31 37 30 38 35 7d 20 49 66 20 74 68 65   {F17085} If the
323c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
323d0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
323e0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
323f0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
32400 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
32410 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20  eturn 1.  {END} 
32420 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74  This seems count
32430 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e  er-intuitive sin
32440 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68  ce.** clearly th
32450 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62  e mutex cannot b
32460 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65  e held if it doe
32470 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75  s not exist.  Bu
32480 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61  t the.** the rea
32490 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f  son the mutex do
324a0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20  es not exist is 
324b0 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  because the buil
324c0 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e  d is not.** usin
324d0 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20  g mutexes.  And 
324e0 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74  we do not want t
324f0 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74  he assert() cont
32500 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61  aining the.** ca
32510 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ll to sqlite3_mu
32520 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61  tex_held() to fa
32530 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72  il, so a non-zer
32540 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74  o return is.** t
32550 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  he appropriate t
32560 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 46 31  hing to do.  {F1
32570 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65  7086} The sqlite
32580 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
32590 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ) .** interface 
325a0 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
325b0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
325c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
325d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
325e0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
325f0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
32600 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
32610 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
32620 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
32630 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70  I3REF: Mutex Typ
32640 65 73 20 7b 46 31 37 30 30 31 7d 0a 2a 2a 0a 2a  es {F17001}.**.*
32650 2a 20 7b 46 31 37 30 30 32 7d 20 54 68 65 20 5b  * {F17002} The [
32660 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
32670 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
32680 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
32690 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
326a0 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
326b0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
326c0 6e 74 73 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 23 64  nts. {END}.*/.#d
326d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
326e0 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
326f0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
32700 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
32710 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
32720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
32730 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
32740 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
32750 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
32760 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
32770 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
32780 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
32790 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
327a0 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
327b0 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  * sqlite3_releas
327c0 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64  e_memory() */.#d
327d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
327e0 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20  EX_STATIC_PRNG  
327f0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
32800 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64  3_random() */.#d
32810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
32820 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20  EX_STATIC_LRU   
32830 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61      6  /* lru pa
32840 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
32850 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d  * CAPI3REF: Low-
32860 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66  Level Control Of
32870 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 20   Database Files 
32880 7b 46 31 31 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F11300}.**.** {
32890 46 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c  F11301} The [sql
328a0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
328b0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d  l()] interface m
328c0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61  akes a direct ca
328d0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69  ll to the.** xFi
328e0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
328f0 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
32900 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
32910 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a  ject associated.
32920 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ** with a partic
32930 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64  ular database id
32940 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
32950 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
32960 20 7b 46 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a   {F11302} The.**
32970 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32980 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d  abase is the nam
32990 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68  e assigned to th
329a0 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68  e database by th
329b0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61  e.** <a href="la
329c0 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e  ng_attach.html">
329d0 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63  ATTACH</a> SQL c
329e0 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e  ommand that open
329f0 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  ed the.** databa
32a00 73 65 2e 20 7b 46 31 31 33 30 33 7d 20 54 6f 20  se. {F11303} To 
32a10 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e  control the main
32a20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
32a30 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  use the name "ma
32a40 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c  in".** or a NULL
32a50 20 70 6f 69 6e 74 65 72 2e 20 7b 46 31 31 33 30   pointer. {F1130
32a60 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  4} The third and
32a70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
32a80 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  rs to this routi
32a90 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  ne.** are passed
32aa0 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67   directly throug
32ab0 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20  h to the second 
32ac0 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65  and third parame
32ad0 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78  ters of.** the x
32ae0 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
32af0 6f 64 2e 20 20 7b 46 31 31 33 30 35 7d 20 54 68  od.  {F11305} Th
32b00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
32b10 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  f the xFileContr
32b20 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63  ol.** method bec
32b30 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20  omes the return 
32b40 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f  value of this ro
32b50 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  utine..**.** {F1
32b60 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63  1306} If the sec
32b70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a  ond parameter (z
32b80 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74  DbName) does not
32b90 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20   match the name 
32ba0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64  of any.** open d
32bb0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68  atabase file, th
32bc0 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  en SQLITE_ERROR 
32bd0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 46 31  is returned. {F1
32be0 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72  1307} This error
32bf0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20  .** code is not 
32c00 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77  remembered and w
32c10 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c  ill not be recal
32c20 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  led by [sqlite3_
32c30 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72  errcode()].** or
32c40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
32c50 28 29 5d 2e 20 7b 55 31 31 33 30 38 7d 20 54 68  ()]. {U11308} Th
32c60 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69  e underlying xFi
32c70 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
32c80 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72   might.** also r
32c90 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52  eturn SQLITE_ERR
32ca0 4f 52 2e 20 20 7b 55 31 31 33 30 39 7d 20 54 68  OR.  {U11309} Th
32cb0 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f  ere is no way to
32cc0 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74   distinguish bet
32cd0 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72  ween.** an incor
32ce0 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64  rect zDbName and
32cf0 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
32d00 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65   return from the
32d10 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78   underlying.** x
32d20 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
32d30 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  od. {END}.**.** 
32d40 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
32d50 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
32d60 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  E].*/.int sqlite
32d70 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73  3_file_control(s
32d80 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
32d90 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e  har *zDbName, in
32da0 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t op, void*);../
32db0 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61  *.** Undo the ha
32dc0 63 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73  ck that converts
32dd0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
32de0 74 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72  types to integer
32df0 20 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f   for.** builds o
32e00 6e 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74  n processors wit
32e10 68 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f  hout floating po
32e20 69 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  int support..*/.
32e30 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
32e40 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
32e50 54 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65  T.# undef double
32e60 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
32e70 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f  __cplusplus.}  /
32e80 2a 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78  * End of the 'ex
32e90 74 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20  tern "C"' block 
32ea0 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66  */.#endif.#endif
32eb0 0a                                               .