/ Hex Artifact Content
Login

Artifact 0d6d4b9d18f1d0b058a7a543ffa777bd5fbf4a99:


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 32 20 32 30 30 37 2f  in,v 1.272 2007/
05f0: 31 31 2f 33 30 20 30 31 3a 30 36 3a 31 37 20 64  11/30 01:06:17 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 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F10100}.**.** {F
0850: 31 30 31 30 31 7d 20 54 68 65 20 76 65 72 73 69  10101} The versi
0860: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
0870: 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74   library is cont
0880: 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c  ained in the sql
0890: 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72  ite3.h.** header
08a0: 20 66 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69   file in a #defi
08b0: 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ne named SQLITE_
08c0: 56 45 52 53 49 4f 4e 2e 20 7b 46 31 30 31 30 32  VERSION. {F10102
08d0: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
08e0: 53 49 4f 4e 0a 2a 2a 20 6d 61 63 72 6f 20 72 65  SION.** macro re
08f0: 73 6f 6c 76 65 73 20 74 6f 20 61 20 73 74 72 69  solves to a stri
0900: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2a 0a  ng constant..**.
0910: 2a 2a 20 7b 46 31 30 31 30 33 7d 20 54 68 65 20  ** {F10103} The 
0920: 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20 53 51  format of the SQ
0930: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 73 74 72  LITE_VERSION str
0940: 69 6e 67 20 69 73 20 22 58 2e 59 2e 5a 22 2c 20  ing is "X.Y.Z", 
0950: 77 68 65 72 65 0a 2a 2a 20 58 20 69 73 20 74 68  where.** X is th
0960: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20  e major version 
0970: 6e 75 6d 62 65 72 2c 20 59 20 69 73 20 74 68 65  number, Y is the
0980: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0990: 75 6d 62 65 72 20 61 6e 64 20 5a 0a 2a 2a 20 69  umber and Z.** i
09a0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
09b0: 6d 62 65 72 2e 20 20 54 68 65 20 58 2e 59 2e 5a  mber.  The X.Y.Z
09c0: 20 6d 69 67 68 74 20 62 65 20 66 6f 6c 6c 6f 77   might be follow
09d0: 65 64 20 62 79 20 22 61 6c 70 68 61 22 20 6f 72  ed by "alpha" or
09e0: 20 22 62 65 74 61 22 2e 0a 2a 2a 20 46 6f 72 20   "beta"..** For 
09f0: 65 78 61 6d 70 6c 65 20 22 33 2e 31 2e 31 62 65  example "3.1.1be
0a00: 74 61 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 58  ta"..**.** The X
0a10: 20 76 61 6c 75 65 20 69 73 20 61 6c 77 61 79 73   value is always
0a20: 20 33 20 69 6e 20 53 51 4c 69 74 65 2e 20 20 54   3 in SQLite.  T
0a30: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he X value only 
0a40: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a50: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0a60: 69 62 69 6c 69 74 79 20 69 73 20 62 72 6f 6b 65  ibility is broke
0a70: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0a80: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a  to never break.*
0a90: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
0aa0: 61 74 69 62 69 6c 69 74 79 2e 20 20 54 68 65 20  atibility.  The 
0ab0: 59 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61  Y value only cha
0ac0: 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nges when.** the
0ad0: 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61  re are major fea
0ae0: 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74  ture enhancement
0af0: 73 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61  s that are forwa
0b00: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a  rds compatible.*
0b10: 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61  * but not backwa
0b20: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20  rds compatible. 
0b30: 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20   The Z value is 
0b40: 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68  incremented with
0b50: 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65  .** each release
0b60: 20 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b   but resets back
0b70: 20 74 6f 20 30 20 77 68 65 6e 20 59 20 69 73 20   to 0 when Y is 
0b80: 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a  incremented..**.
0b90: 2a 2a 20 7b 46 31 30 31 30 34 7d 20 54 68 65 20  ** {F10104} The 
0ba0: 23 64 65 66 69 6e 65 20 6e 61 6d 65 64 20 53 51  #define named SQ
0bb0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0bc0: 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65  BER is an intege
0bd0: 72 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 76 61  r with.** the va
0be0: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0bf0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f   Y*1000 + Z). Fo
0c00: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76  r example, for v
0c10: 65 72 73 69 6f 6e 20 22 33 2e 35 2e 33 22 2c 20  ersion "3.5.3", 
0c20: 0a 2a 2a 20 53 51 4c 49 54 45 5f 56 45 52 53 49  .** SQLITE_VERSI
0c30: 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 73 65 74  ON_NUMBER is set
0c40: 20 74 6f 20 33 30 30 35 30 30 33 2e 20 54 6f 20   to 3005003. To 
0c50: 64 65 74 65 63 74 20 69 66 20 74 68 65 79 20 61  detect if they a
0c60: 72 65 20 75 73 69 6e 67 20 0a 2a 2a 20 76 65 72  re using .** ver
0c70: 73 69 6f 6e 20 33 2e 35 2e 33 20 6f 72 20 67 72  sion 3.5.3 or gr
0c80: 65 61 74 65 72 20 61 74 20 63 6f 6d 70 69 6c 65  eater at compile
0c90: 20 74 69 6d 65 2c 20 70 72 6f 67 72 61 6d 73 20   time, programs 
0ca0: 6d 61 79 20 75 73 65 20 74 68 65 20 74 65 73 74  may use the test
0cb0: 20 0a 2a 2a 20 28 53 51 4c 49 54 45 5f 56 45 52   .** (SQLITE_VER
0cc0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e 3d 33 30 30  SION_NUMBER>=300
0cd0: 35 30 30 33 29 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  5003). {END}.**.
0ce0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0cf0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0d00: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
0d10: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0d20: 65 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  er()]..*/.#defin
0d30: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0d40: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0d50: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0d60: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0d70: 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42  R --VERSION-NUMB
0d80: 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ER--../*.** CAPI
0d90: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
0da0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0db0: 75 6d 62 65 72 73 20 7b 46 31 30 31 31 30 7d 0a  umbers {F10110}.
0dc0: 2a 2a 0a 2a 2a 20 7b 46 31 30 31 31 31 7d 20 54  **.** {F10111} T
0dd0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
0de0: 72 73 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  rsion() and sqli
0df0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
0e00: 75 6d 62 65 72 28 29 0a 2a 2a 20 72 6f 75 74 69  umber().** routi
0e10: 6e 65 73 20 72 65 74 75 72 6e 20 76 61 6c 75 65  nes return value
0e20: 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
0e30: 74 68 65 20 68 65 61 64 65 72 20 63 6f 6e 73 74  the header const
0e40: 61 6e 74 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ants.** [SQLITE_
0e50: 56 45 52 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51  VERSION] and [SQ
0e60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e70: 42 45 52 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  BER].  The value
0e80: 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  s returned.** by
0e90: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 20 73   this routines s
0ea0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69  hould only be di
0eb0: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
0ec0: 20 68 65 61 64 65 72 20 76 61 6c 75 65 73 0a 2a   header values.*
0ed0: 2a 20 69 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65  * if you compile
0ee0: 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 75 73   your program us
0ef0: 69 6e 67 20 61 6e 20 73 71 6c 69 74 65 33 2e 68  ing an sqlite3.h
0f00: 20 68 65 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a   header from a.*
0f10: 2a 20 64 69 66 66 65 72 65 6e 74 20 76 65 72 73  * different vers
0f20: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
0f30: 61 74 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f  at the version o
0f40: 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 79 6f  f the library yo
0f50: 75 0a 2a 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73  u.** link agains
0f60: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 31 32  t..**.** {F10112
0f70: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65  } The sqlite3_ve
0f80: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
0f90: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
0fa0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65   the text of the
0fb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
0fc0: 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20 20 54 68  ION] string.  Th
0fd0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0fe0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0ff0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
1000: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
1010: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1020: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
1030: 54 68 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  The function.** 
1040: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
1050: 44 4c 4c 20 75 73 65 72 73 20 77 68 6f 20 63 61  DLL users who ca
1060: 6e 20 6f 6e 6c 79 20 61 63 63 65 73 73 20 66 75  n only access fu
1070: 6e 63 74 69 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a  nctions and not.
1080: 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ** constants wit
1090: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a  hin the DLL..*/.
10a0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f  SQLITE_EXTERN co
10b0: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33  nst char sqlite3
10c0: 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73  _version[];.cons
10d0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
10e0: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
10f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1100: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1110: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1120: 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20  PI3REF: Test To 
1130: 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61  See If The Libra
1140: 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65  ry Is Threadsafe
1150: 20 7b 46 31 30 32 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F10200}.**.** 
1160: 7b 46 31 30 32 30 31 7d 20 54 68 65 20 73 71 6c  {F10201} The sql
1170: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1180: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1190: 73 20 54 52 55 45 20 28 6e 6f 6e 7a 65 72 6f 29  s TRUE (nonzero)
11a0: 20 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 77   .** if SQLite w
11b0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
11c0: 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  .** all of its m
11d0: 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 61  utexes enabled a
11e0: 6e 64 20 69 73 20 74 68 75 73 20 74 68 72 65 61  nd is thus threa
11f0: 64 73 61 66 65 2e 20 20 49 74 20 72 65 74 75 72  dsafe.  It retur
1200: 6e 73 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  ns.** zero if th
1210: 65 20 70 61 72 74 69 63 75 6c 61 72 20 62 75 69  e particular bui
1220: 6c 64 20 69 73 20 66 6f 72 20 73 69 6e 67 6c 65  ld is for single
1230: 2d 74 68 72 65 61 64 65 64 20 6f 70 65 72 61 74  -threaded operat
1240: 69 6f 6e 0a 2a 2a 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ion.** only..**.
1250: 2a 2a 20 52 65 61 6c 6c 79 20 61 6c 6c 20 74 68  ** Really all th
1260: 69 73 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  is routine does 
1270: 69 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  is return true i
1280: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1290: 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  piled.** with th
12a0: 65 20 2d 44 53 51 4c 49 54 45 5f 54 48 52 45 41  e -DSQLITE_THREA
12b0: 44 53 41 46 45 3d 31 20 6f 70 74 69 6f 6e 20 61  DSAFE=1 option a
12c0: 6e 64 20 66 61 6c 73 65 20 69 66 0a 2a 2a 20 63  nd false if.** c
12d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 2d 44 53  ompiled with -DS
12e0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12f0: 3d 30 2e 20 20 49 66 20 53 51 4c 69 74 65 20 75  =0.  If SQLite u
1300: 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63  ses an.** applic
1310: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6d 75  ation-defined mu
1320: 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c 20 6d  tex subsystem, m
1330: 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65 6d 2c  alloc subsystem,
1340: 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20 73 65   collating.** se
1350: 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53 51 4c  quence, VFS, SQL
1360: 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f 67 72   function, progr
1370: 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20 63 6f  ess callback, co
1380: 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20 65 78  mmit hook,.** ex
1390: 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74 68 65  tension, or othe
13a0: 72 20 61 63 63 65 73 73 6f 72 69 65 73 20 61 6e  r accessories an
13b0: 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e 73 20  d these add-ons 
13c0: 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72 65 61  are not.** threa
13d0: 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c 65 61  dsafe, then clea
13e0: 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e 61 74  rly the combinat
13f0: 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ion will not be 
1400: 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20 65 69  threadsafe.** ei
1410: 74 68 65 72 2e 20 20 48 65 6e 63 65 2c 20 74 68  ther.  Hence, th
1420: 69 73 20 72 6f 75 74 69 6e 65 20 6e 65 76 65 72  is routine never
1430: 20 72 65 70 6f 72 74 73 20 74 68 61 74 20 74 68   reports that th
1440: 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 73 20  e library.** is 
1450: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
1460: 20 74 68 72 65 61 64 73 61 66 65 2c 20 6f 6e 6c   threadsafe, onl
1470: 79 20 77 68 65 6e 20 69 74 20 69 73 20 67 75 61  y when it is gua
1480: 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 74  ranteed not.** t
1490: 6f 20 62 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  o be..**.** This
14a0: 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d 65 6e   is an experimen
14b0: 74 61 6c 20 41 50 49 20 61 6e 64 20 6d 61 79 20  tal API and may 
14c0: 67 6f 20 61 77 61 79 20 6f 72 20 63 68 61 6e 67  go away or chang
14d0: 65 20 69 6e 20 66 75 74 75 72 65 0a 2a 2a 20 72  e in future.** r
14e0: 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
14f0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1500: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
1510: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
1520: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
1530: 61 6e 64 6c 65 20 7b 46 31 31 30 30 30 7d 0a 2a  andle {F11000}.*
1540: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
1550: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1560: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1570: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1580: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a  nstance of the.*
1590: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  * opaque structu
15a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
15b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
15c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
15d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
15e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
15f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
1600: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1610: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
1630: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1640: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
1650: 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b  ructors.** and [
1660: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1670: 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74   is its destruct
1680: 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  or.  There are m
1690: 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66  any other interf
16a0: 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73  aces.** (such as
16b0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16c0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
16d0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
16e0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
16f0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1700: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
1710: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
1720: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69  e methods on thi
1730: 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  s.** object..*/.
1740: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1750: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
1760: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1770: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
1780: 20 54 79 70 65 73 20 7b 46 31 30 33 30 30 7d 0a   Types {F10300}.
1790: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
17a0: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
17b0: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
17c0: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
17d0: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
17e0: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
17f0: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
1800: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1810: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1820: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
1830: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1840: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1850: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1860: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
1870: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
1880: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
1890: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
18a0: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
18b0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
18c0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
18d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
18e0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
18f0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
1900: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1910: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1920: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
1930: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1940: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1950: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1960: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
1970: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1980: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
1990: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
19a0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
19b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
19c0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
19d0: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
19e0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
19f0: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
1a00: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
1a10: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
1a20: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
1a30: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1a40: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
1a50: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
1a60: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
1a70: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
1a80: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
1a90: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
1aa0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
1ab0: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65  g-point.*/.#ifde
1ac0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
1ad0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
1ae0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
1af0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
1b00: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1b10: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
1b20: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1b30: 20 7b 46 31 31 31 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F11100}.**.** 
1b40: 7b 46 31 31 31 30 31 7d 20 54 68 65 20 73 71 6c  {F11101} The sql
1b50: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 6e 74  ite3_close() int
1b60: 65 72 66 61 63 65 20 69 73 20 74 68 65 20 64 65  erface is the de
1b70: 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
1b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1b90: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ject..**.** {F11
1ba0: 31 30 32 7d 20 41 6c 6c 20 53 51 4c 20 73 74 61  102} All SQL sta
1bb0: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1bc0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bd0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1be0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1bf0: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1c00: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1c10: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1c20: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1c30: 6f 72 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ore sqlite3_clos
1c40: 65 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f  e() is called. O
1c50: 74 68 65 72 77 69 73 65 2c 20 73 71 6c 69 74 65  therwise, sqlite
1c60: 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 72 6e  3_close() return
1c70: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
1c80: 20 61 6e 64 20 64 61 74 61 62 61 73 65 20 63 6f   and database co
1c90: 6e 6e 65 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  nnection remains
1ca0: 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31   open..**.** {U1
1cb0: 31 31 30 33 7d 20 43 61 6c 6c 69 6e 67 20 73 71  1103} Calling sq
1cc0: 6c 69 74 65 33 5f 63 6c 6f 73 65 20 6f 6e 20 61  lite3_close on a
1cd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ce0: 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 0a 2a  tion that has .*
1cf0: 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 63  * already been c
1d00: 6c 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e  losed results in
1d10: 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1d20: 69 6f 72 2e 20 20 7b 55 31 31 31 30 34 7d 20 49  ior.  {U11104} I
1d30: 66 20 0a 2a 2a 20 6f 74 68 65 72 20 69 6e 74 65  f .** other inte
1d40: 72 66 61 63 65 73 20 74 68 61 74 20 72 65 66 65  rfaces that refe
1d50: 72 65 6e 63 65 20 74 68 65 20 73 61 6d 65 20 64  rence the same d
1d60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d70: 6f 6e 20 61 72 65 20 0a 2a 2a 20 70 65 6e 64 69  on are .** pendi
1d80: 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 74 68  ng (either in th
1d90: 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 6f 72  e same thread or
1da0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
1db0: 72 65 61 64 73 29 20 77 68 65 6e 20 0a 2a 2a 20  reads) when .** 
1dc0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
1dd0: 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1de0: 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1df0: 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 73  undefined and is
1e00: 0a 2a 2a 20 61 6c 6d 6f 73 74 20 63 65 72 74 61  .** almost certa
1e10: 69 6e 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  inly undesirable
1e20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e30: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
1e40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
1e50: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
1e60: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
1e70: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
1e80: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
1e90: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
1ea0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
1eb0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
1ec0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
1ed0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
1ee0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
1ef0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
1f00: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
1f10: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f20: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
1f30: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
1f40: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69  erface.**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  s interface is u
1f60: 73 65 64 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d  sed to do a one-
1f70: 74 69 6d 65 20 65 76 61 6c 75 61 74 61 74 69 6f  time evaluatatio
1f80: 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20  n of zero.** or 
1f90: 6d 6f 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  more SQL stateme
1fa0: 6e 74 73 2e 20 20 55 54 46 2d 38 20 74 65 78 74  nts.  UTF-8 text
1fb0: 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
1fc0: 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20  ements to.** be 
1fd0: 65 76 61 6c 75 74 65 64 20 69 73 20 70 61 73 73  evaluted is pass
1fe0: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
1ff0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
2000: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  The statements.*
2010: 2a 20 61 72 65 20 70 72 65 70 61 72 65 64 20 6f  * are prepared o
2020: 6e 65 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 20  ne by one using 
2030: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2040: 28 29 5d 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a  ()], evaluated.*
2050: 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2060: 5f 73 74 65 70 28 29 5d 2c 20 74 68 65 6e 20 64  _step()], then d
2070: 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b  estroyed using [
2080: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2090: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e  ()]..**.** If on
20a0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
20b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20c0: 61 72 65 20 71 75 65 72 69 65 73 2c 20 74 68 65  are queries, the
20d0: 6e 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 62 61 63  n.** the callbac
20e0: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69  k function speci
20f0: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  fied by the 3rd 
2100: 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2110: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2120: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
2130: 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20   query result.  
2140: 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  This callback.**
2150: 20 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79   should normally
2160: 20 72 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74   return 0.  If t
2170: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
2180: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  rns a non-zero.*
2190: 2a 20 76 61 6c 75 65 20 74 68 65 6e 20 74 68 65  * value then the
21a0: 20 71 75 65 72 79 20 69 73 20 61 62 6f 72 74 65   query is aborte
21b0: 64 2c 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  d, all subsequen
21c0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
21d0: 0a 2a 2a 20 61 72 65 20 73 6b 69 70 70 65 64 20  .** are skipped 
21e0: 61 6e 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  and the sqlite3_
21f0: 65 78 65 63 28 29 20 66 75 6e 63 74 69 6f 6e 20  exec() function 
2200: 72 65 74 75 72 6e 73 20 74 68 65 20 5b 53 51 4c  returns the [SQL
2210: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
2220: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2230: 74 65 72 20 74 6f 20 74 68 69 73 20 69 6e 74 65  ter to this inte
2240: 72 66 61 63 65 20 69 73 20 61 6e 20 61 72 62 69  rface is an arbi
2250: 74 72 61 72 79 20 70 6f 69 6e 74 65 72 20 74 68  trary pointer th
2260: 61 74 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  at is.** passed 
2270: 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2280: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2290: 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61   as its first pa
22a0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
22b0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
22c0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
22d0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
22e0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 6f   number of.** co
22f0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 71 75 65  lumns in the que
2300: 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 65 20  ry result.  The 
2310: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2320: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
2330: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2340: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20  strings holding 
2350: 74 68 65 20 76 61 6c 75 65 73 20 66 6f 72 20 65  the values for e
2360: 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73  ach column.** as
2370: 20 65 78 74 72 61 63 74 65 64 20 75 73 69 6e 67   extracted using
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2390: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  _text()]..** The
23a0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
23b0: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
23c0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74  s an array of st
23d0: 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65  rings.** obtaine
23e0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
23f0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20  _column_name()] 
2400: 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74  and holding.** t
2410: 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68  he names of each
2420: 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54   column..**.** T
2430: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2440: 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c  tion may be NULL
2450: 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65 72 69  , even for queri
2460: 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63  es.  A NULL.** c
2470: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 61  allback is not a
2480: 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a 75 73  n error.  It jus
2490: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  t means that no 
24a0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c  callback.** will
24b0: 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   be invoked..**.
24c0: 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  ** If an error o
24d0: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
24e0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
24f0: 67 20 74 68 65 20 53 51 4c 20 28 62 75 74 0a 2a  g the SQL (but.*
2500: 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78 65 63  * not while exec
2510: 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  uting the callba
2520: 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70 70 72  ck) then an appr
2530: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a  opriate error.**
2540: 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74   message is writ
2550: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
2560: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2570: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2580: 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73 67 20   and.** *errmsg 
2590: 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
25a0: 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65   to that message
25b0: 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  .  The calling f
25c0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65  unction.** is re
25d0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
25e0: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
25f0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2600: 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 65  free()]..** If e
2610: 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c 20 74 68 65  rrmsg==NULL, the
2620: 6e 20 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73 61  n no error messa
2630: 67 65 20 69 73 20 65 76 65 72 20 77 72 69 74 74  ge is ever writt
2640: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  en..**.** The re
2650: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 69 73  turn value is is
2660: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68   SQLITE_OK if th
2670: 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72  ere are no error
2680: 73 20 61 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74  s and.** some ot
2690: 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  her [SQLITE_OK |
26a0: 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 20 69 66   return code] if
26b0: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
26c0: 6f 72 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72  or.  .** The par
26d0: 74 69 63 75 6c 61 72 20 72 65 74 75 72 6e 20 76  ticular return v
26e0: 61 6c 75 65 20 64 65 70 65 6e 64 73 20 6f 6e 20  alue depends on 
26f0: 74 68 65 20 74 79 70 65 20 6f 66 20 65 72 72 6f  the type of erro
2700: 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  r. .**.*/.int sq
2710: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
2720: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
2730: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2740: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
2750: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
2760: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
2770: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
2780: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2790: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74  SQL to be evalut
27a0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
27b0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
27c0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
27d0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
27e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
27f0: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
2800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2810: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
2820: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
2830: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
2840: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
2850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2860: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
2870: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
2880: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2890: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
28a0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
28b0: 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d  QLITE_OK.**.** M
28c0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
28d0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
28e0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
28f0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
2900: 73 68 6f 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69  shown.** above i
2910: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
2920: 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20  ates success or 
2930: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  failure..**.** T
2940: 68 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  he result codes 
2950: 61 62 6f 76 65 20 61 72 65 20 74 68 65 20 6f 6e  above are the on
2960: 6c 79 20 6f 6e 65 73 20 72 65 74 75 72 6e 65 64  ly ones returned
2970: 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
2980: 73 0a 2a 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e  s.** default con
2990: 66 69 67 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77  figuration.  How
29a0: 65 76 65 72 2c 20 74 68 65 20 5b 73 71 6c 69 74  ever, the [sqlit
29b0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
29c0: 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41  lt_codes()].** A
29d0: 50 49 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  PI can be used t
29e0: 6f 20 73 65 74 20 61 20 64 61 74 61 62 61 73 65  o set a database
29f0: 20 63 6f 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72   connectoin to r
2a00: 65 74 75 72 6e 20 6d 6f 72 65 20 64 65 74 61 69  eturn more detai
2a10: 6c 65 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  led.** result co
2a20: 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  des..**.** See a
2a30: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
2a40: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
2a50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2a60: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .**.*/.#define S
2a70: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
2a80: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
2a90: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
2aa0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
2ab0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
2ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
2ad0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
2ae0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
2af0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
2b00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b10: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
2b20: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49    /* NOT USED. I
2b30: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
2b40: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
2b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b60: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
2b70: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
2b80: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
2b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2ba0: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
2bb0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
2bc0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
2bd0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
2be0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
2bf0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
2c00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
2c10: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
2c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
2c30: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
2c40: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
2c50: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
2c60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c70: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
2c80: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
2c90: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
2ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
2cb0: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
2cc0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
2cd0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
2ce0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
2cf0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
2d00: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
2d10: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
2d20: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
2d30: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
2d40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
2d50: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
2d60: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
2d70: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
2d80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d90: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
2da0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
2db0: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
2dc0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
2dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
2de0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
2df0: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
2e00: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
2e10: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
2e20: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
2e30: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
2e40: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
2e50: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
2e60: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
2e70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
2e80: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
2e90: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
2ea0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
2eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
2ec0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
2ed0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
2ee0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
2ef0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
2f00: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
2f10: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
2f20: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
2f30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2f40: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
2f50: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
2f60: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2f70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
2f80: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
2f90: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
2fa0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
2fb0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
2fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
2fd0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
2fe0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
2ff0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
3000: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
3010: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
3020: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
3030: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
3040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
3050: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
3060: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
3070: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
3080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
3090: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
30a0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
30b0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
30c0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
30d0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
30e0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
30f0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
3100: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3110: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
3120: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
3130: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
3140: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
3150: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
3160: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
3170: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3180: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
3190: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
31a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
31b0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
31c0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
31d0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
31e0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
31f0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
3200: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
3210: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
3220: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
3230: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
3240: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
3250: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
3260: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
3270: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
3280: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
3290: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
32a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
32b0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
32c0: 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  s.**.** In its d
32d0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
32e0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
32f0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
3300: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
3310: 65 72 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64  er.** result cod
3320: 65 73 20 64 65 73 63 72 69 62 65 64 20 61 74 20  es described at 
3330: 72 65 73 75 6c 74 2d 63 6f 64 65 73 2e 20 20 48  result-codes.  H
3340: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
3350: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
3360: 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65  t.** many of the
3370: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
3380: 61 72 65 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67  are too course-g
3390: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
33a0: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
33b0: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
33c0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
33d0: 6d 73 20 61 73 20 75 73 65 72 73 20 6d 69 67 68  ms as users migh
33e0: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
33f0: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3400: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3410: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3420: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3430: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3440: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3450: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
3460: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
3470: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
3480: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
3490: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
34a0: 72 73 2e 20 20 54 68 65 20 65 78 74 65 6e 64 65  rs.  The extende
34b0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
34c0: 72 65 20 65 6e 61 62 6c 65 64 20 28 6f 72 20 64  re enabled (or d
34d0: 69 73 61 62 6c 65 64 29 20 66 6f 72 20 0a 2a 2a  isabled) for .**
34e0: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a   each database.*
34f0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  * connection usi
3500: 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
3510: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
3520: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
3530: 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65   .** Some of the
3540: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
3550: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3560: 20 61 72 65 20 6c 69 73 74 65 64 20 61 62 6f 76   are listed abov
3570: 65 2e 0a 2a 2a 20 57 65 20 65 78 70 65 63 74 20  e..** We expect 
3580: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
3590: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
35a0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
35b0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
35c0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
35d0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
35e0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
35f0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
3600: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
3610: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
3620: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
3630: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 73 79 6d  ..** .** The sym
3640: 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61  bolic name for a
3650: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
3660: 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f  t code always co
3670: 6e 74 61 69 6e 73 20 61 20 72 65 6c 61 74 65 64  ntains a related
3680: 0a 2a 2a 20 70 72 69 6d 61 72 79 20 72 65 73 75  .** primary resu
3690: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65  lt code as a pre
36a0: 66 69 78 2e 20 20 50 72 69 6d 61 72 79 20 72 65  fix.  Primary re
36b0: 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61  sult codes conta
36c0: 69 6e 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 22  in a single.** "
36d0: 5f 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 45  _" character.  E
36e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
36f0: 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f  odes contain two
3700: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
3710: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 54 68 65 20  racters..** The 
3720: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
3730: 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73   an extended res
3740: 75 6c 74 20 63 6f 64 65 20 63 61 6e 20 62 65 20  ult code can be 
3750: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 69 74 73  converted to its
3760: 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
3770: 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  g primary result
3780: 20 63 6f 64 65 20 62 79 20 6d 61 73 6b 69 6e 67   code by masking
3790: 20 6f 66 66 20 74 68 65 20 6c 6f 77 65 72 20 38   off the lower 8
37a0: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   bytes..**.** Th
37b0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
37c0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
37d0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
37e0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
37f0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
3800: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
3810: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
3820: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
3830: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
3840: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3850: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
3860: 44 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  D    (SQLITE_IOE
3870: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
3880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3890: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
38a0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
38b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
38c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
38d0: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
38e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
38f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3900: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
3910: 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f  C     (SQLITE_IO
3920: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
3930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3940: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
3950: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3960: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
3970: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
3980: 54 41 54 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAT         (SQL
3990: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
39a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
39b0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
39c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
39d0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
39e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
39f0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
3a00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3a10: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
3a20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
3a30: 45 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 51  ELETE        (SQ
3a40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
3a50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3a60: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
3a70: 45 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  ED       (SQLITE
3a80: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
3a90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3aa0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
3ab0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3ac0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 0a 2f  RR | (12<<8))../
3ad0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
3ae0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
3af0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
3b00: 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20  .** Combination 
3b10: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3b20: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
3b30: 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74  used as the.** t
3b40: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
3b50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
3b60: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
3b70: 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75  ce and.** as fou
3b80: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
3b90: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
3ba0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
3bb0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
3bc0: 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  .**.*/.#define S
3bd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
3be0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
3bf0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
3c00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
3c10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
3c20: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
3c30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
3c40: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
3c50: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
3c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
3c70: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
3c80: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
3c90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
3ca0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
3cb0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
3cc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3cd0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3ce0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
3cf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3d00: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
3d10: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
3d20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
3d30: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
3d40: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
3d50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
3d60: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3d70: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
3d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
3d90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
3da0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
3db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
3dc0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
3dd0: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
3de0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
3df0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
3e00: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
3e10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
3e20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
3e30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
3e40: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
3e50: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
3e60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
3e70: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
3e80: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
3e90: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
3ea0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  f the following.
3eb0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
3ec0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
3ed0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
3ee0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
3ef0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
3f00: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
3f10: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
3f20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
3f30: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
3f40: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
3f50: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
3f60: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
3f70: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
3f80: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
3f90: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
3fa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
3fb0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
3fc0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
3fd0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
3fe0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
3ff0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
4000: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
4010: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
4020: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
4030: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
4040: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
4050: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
4060: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
4070: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
4080: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
4090: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
40a0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
40b0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
40c0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
40d0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
40e0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
40f0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
4100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4110: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
4120: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
4130: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
4140: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
4150: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
4160: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
4170: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
4180: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4190: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
41a0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41c0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
41d0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
41e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
41f0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
4200: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
4210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4220: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
4230: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
4240: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4250: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
4260: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
4270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4280: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
4290: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
42a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
42b0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
42c0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
42d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
42e0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
42f0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4310: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
4320: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
4330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4340: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
4350: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
4360: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
4370: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
4380: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
4390: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
43a0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
43b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
43c0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
43d0: 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76  lowing integer v
43e0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
43f0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
4400: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
4410: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
4420: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
4430: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
4440: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4450: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
4460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4470: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
4480: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
4490: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
44a0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
44b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
44c0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
44d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
44e0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
4510: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
4520: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
4530: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
4540: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
4550: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
4560: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
4570: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
4580: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
4590: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
45a0: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
45b0: 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
45c0: 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68   values as.** th
45d0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
45e0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
45f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
4600: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
4610: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
4620: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
4630: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
4640: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
4650: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
4660: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
4670: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
4680: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54  t be flushed.  T
4690: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
46a0: 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20  ORMAL means .** 
46b0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
46c0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
46d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e    The SQLITE_SYN
46e0: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
46f0: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  s .** to use Mac
4700: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
4710: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
4720: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
4740: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
4750: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4760: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
4770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
4780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4790: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
47a0: 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a    0x00010.../*.*
47b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
47c0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
47d0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
47e0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
47f0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
4800: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
4810: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
4820: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
4830: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
4840: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
4850: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
4860: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
4870: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
4880: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
4890: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
48a0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
48b0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
48c0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
48d0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
48e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
48f0: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
4900: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
4910: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
4920: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
4930: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
4940: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
4950: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
4960: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
4970: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
4980: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
4990: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
49a0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
49b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
49c0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
49d0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
49e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
49f0: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
4a00: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
4a10: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
4a20: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
4a30: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
4a40: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
4a50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
4a60: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
4a70: 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20  he this object. 
4a80: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
4a90: 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68  ines the.** meth
4aa0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
4ab0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
4ac0: 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74  ations against t
4ad0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a  he open file..**
4ae0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
4af0: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
4b00: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
4b10: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
4b20: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
4b30: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
4b40: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
4b50: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
4b60: 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63  nc()..*  The sec
4b70: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e  ond choice is an
4b80: 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  .** OS-X style f
4b90: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51  ullsync.  The SQ
4ba0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66  LITE_SYNC_DATA f
4bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
4bc0: 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74  in to.** indicat
4bd0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
4be0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
4bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
4c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a  de needs to be.*
4c10: 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a  * synced..** .**
4c20: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
4c30: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
4c40: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
4c50: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
4c60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
4c70: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
4c80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4c90: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
4ca0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
4cb0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
4cc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
4cd0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
4ce0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
4cf0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
4d00: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
4d10: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
4d20: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
4d30: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
4d40: 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65  k.  .** The xChe
4d50: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
4d60: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a   method looks.**
4d70: 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64   to see if any d
4d80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4d90: 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68  on, either in th
4da0: 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72  is.** process or
4db0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
4dc0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
4dd0: 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a  ng an RESERVED,.
4de0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
4df0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
4e00: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
4e10: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
4e20: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
4e30: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69  ists and false i
4e40: 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  f not..** .** Th
4e50: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
4e60: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
4e70: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
4e80: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
4e90: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
4ea0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
4eb0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
4ec0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
4ed0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4ee0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
4ef0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
4f00: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
4f10: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  ment.** is an in
4f20: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20  teger opcode.   
4f30: 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  The third.** arg
4f40: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
4f50: 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ic pointer which
4f60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
4f70: 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  be a pointer.** 
4f80: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
4f90: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
4fa0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
4fb0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
4fc0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
4fd0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
4fe0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
4ff0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
5000: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
5010: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
5020: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
5030: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
5040: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
5050: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
5060: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
5070: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
5080: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
5090: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
50a0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
50b0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
50c0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
50d0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f   core reserves o
50e0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
50f0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
5100: 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c   use. .** A [SQL
5110: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
5120: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
5130: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
5140: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
5150: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
5160: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
5170: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
5180: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
5190: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a  ld use opcodes .
51a0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
51b0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
51c0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
51d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
51e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
51f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
5200: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
5210: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
5220: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
5230: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
5240: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
5250: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
5260: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
5270: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
5280: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
5290: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
52a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
52b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
52c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
52d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
52e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
52f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
5300: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
5310: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5320: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
5330: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
5340: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
5350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
5370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
5390: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
53a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
53b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
53d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
53e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
53f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5400: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5410: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
5420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
5430: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
5440: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5450: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
5460: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5470: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
5480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5490: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
54a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
54b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
54c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
54d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
54e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
54f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5500: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5510: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5520: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5530: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5540: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5550: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5560: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5570: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5580: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5590: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
55a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
55b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
55c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
55d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
55e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
55f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5600: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5610: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5620: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5630: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5640: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5650: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5660: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5670: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5680: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5690: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
56a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
56b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
56c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
56d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
56e0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
56f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
5700: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5710: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
5720: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
5730: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5740: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
5750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5760: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
5770: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
5780: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
5790: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
57a0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
57b0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
57c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
57d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
57e0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
57f0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
5800: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
5810: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
5820: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
5830: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
5840: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
5850: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
5860: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
5870: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
5880: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
5890: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
58a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
58b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
58c0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
58d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
58e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
58f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
5900: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
5910: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
5920: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
5930: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5940: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
5950: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5960: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
5970: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
5980: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
5990: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
59a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
59b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
59c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
59d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
59e0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
59f0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
5a00: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
5a10: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
5a20: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
5a30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5a40: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
5a50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5a60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
5a70: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
5a80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
5a90: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
5aa0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
5ab0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
5ac0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
5ad0: 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  ases the xFileCo
5ae0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
5af0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
5b00: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
5b10: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
5b20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b30: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
5b40: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
5b50: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5b60: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
5b70: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
5b80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5b90: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
5ba0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
5bb0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
5bc0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 20 54 68 69   points to.  Thi
5bd0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
5be0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
5bf0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
5c00: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
5c10: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
5c20: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
5c30: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
5c40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
5c50: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
5c60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5c70: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
5c80: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5c90: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5ca0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
5cb0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
5cc0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
5cd0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
5ce0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
5cf0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
5d00: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5d10: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5d20: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
5d30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
5d40: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
5d50: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
5d60: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d70: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
5d80: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
5d90: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
5da0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
5db0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
5dc0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5dd0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
5de0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
5df0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5e00: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
5e10: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
5e20: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
5e30: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
5e40: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
5e50: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  * SQLite core an
5e60: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
5e70: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
5e80: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
5e90: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
5ea0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
5eb0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
5ec0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
5ed0: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  ** The iVersion 
5ee0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
5ef0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
5f00: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72  larger for futur
5f10: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
5f20: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
5f30: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
5f40: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
5f50: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
5f60: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
5f70: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
5f80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
5f90: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
5fa0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5fb0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
5fc0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
5fd0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
5fe0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
5ff0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
6000: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
6010: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
6020: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
6030: 65 67 69 73 74 65 72 65 64 20 76 66 73 20 6d 6f  egistered vfs mo
6040: 64 75 6c 65 73 20 61 72 65 20 6b 65 70 74 20 6f  dules are kept o
6050: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
6060: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
6070: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
6080: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
6090: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
60a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
60b0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
60c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
60d0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
60e0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
60f0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
6100: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
6110: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
6120: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a  ches the list..*
6130: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
6140: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
6150: 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65 20 73   fields in the s
6160: 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73  qlite3_vfs .** s
6170: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
6180: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
6190: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
61a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
61b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
61c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
61d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
61e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
61f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
6200: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
6210: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
6220: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
6230: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
6240: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
6250: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
6260: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
6270: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
6280: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
6290: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
62a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
62b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
62c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
62d0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
62e0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
62f0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
6300: 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20  e string passed 
6310: 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73  to.** xOpen() is
6320: 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65   a full pathname
6330: 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79   as generated by
6340: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
6350: 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65   and.** that the
6360: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
6370: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
6380: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
6390: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
63a0: 20 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65    So the [sqlite
63b0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
63c0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
63d0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
63e0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
63f0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
6400: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
6410: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  son..**.** The f
6420: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6430: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f   xOpen() is a co
6440: 70 79 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20  py of the flags 
6450: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
6460: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6470: 29 5d 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33  )].  If [sqlite3
6480: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
6490: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 0a 2a  ite3_open16()].*
64a0: 2a 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  * is used, then 
64b0: 66 6c 61 67 73 20 69 73 20 5b 53 51 4c 49 54 45  flags is [SQLITE
64c0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
64d0: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
64e0: 43 52 45 41 54 45 5d 2e 0a 2a 2a 20 49 66 20 78  CREATE]..** If x
64f0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
6500: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
6510: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
6520: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
6530: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
6540: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
6550: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
6560: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
6570: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69  set..** .** SQLi
6580: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
6590: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
65a0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
65b0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
65c0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
65d0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
65e0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a  g opened:.** .**
65f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
6600: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6610: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6620: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6630: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
6640: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
6650: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
6660: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
6670: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
6680: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
6690: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
66a0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
66b0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
66c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
66d0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
66e0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
66f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
6700: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
6710: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
6720: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
6730: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
6740: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
6750: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
6760: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
6770: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
6780: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
6790: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
67a0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c  ery or rollback,
67b0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
67c0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
67d0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
67e0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
67f0: 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a  is journal are.*
6800: 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20  * also a no-op. 
6810: 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
6820: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
6830: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
6840: 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20  OERR..** Or the 
6850: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
6860: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
6870: 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69  he a database fi
6880: 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f  le will.** be do
6890: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
68a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
68b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
68c0: 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e  ndom order.** an
68d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
68e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
68f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
6900: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
6910: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
6920: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
6930: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
6940: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
6950: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6960: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
6970: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
6980: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
6990: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
69a0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  .** .** The [SQL
69b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
69c0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
69d0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
69e0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
69f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
6a00: 65 64 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61  ed.  This will a
6a10: 6c 77 61 79 73 20 62 65 20 73 65 74 20 66 6f 72  lways be set for
6a20: 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61   TEMP .** databa
6a30: 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73  ses and journals
6a40: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
6a50: 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  nals.  The .** [
6a60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
6a70: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
6a80: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
6a90: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
6aa0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
6ab0: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
6ac0: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
6ad0: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
6ae0: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
6af0: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a  base file..** .*
6b00: 2a 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20  * Space to hold 
6b10: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
6b20: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
6b30: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
6b40: 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  d .** argument t
6b50: 6f 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63  o xOpen is alloc
6b60: 61 74 65 64 20 62 79 20 63 61 6c 6c 65 72 20 28  ated by caller (
6b70: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 29  the SQLite core)
6b80: 2e 20 0a 2a 2a 20 73 7a 4f 73 46 69 6c 65 20 62  . .** szOsFile b
6b90: 79 74 65 73 20 61 72 65 20 61 6c 6c 6f 63 61 74  ytes are allocat
6ba0: 65 64 20 66 6f 72 20 74 68 69 73 20 6f 62 6a 65  ed for this obje
6bb0: 63 74 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ct.  The xOpen m
6bc0: 65 74 68 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20 69  ethod.** fills i
6bd0: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
6be0: 73 70 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  space..** .** Th
6bf0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
6c00: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
6c10: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
6c20: 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20  ESS_EXISTS] .** 
6c30: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
6c40: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
6c50: 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ile,.** or [SQLI
6c60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
6c70: 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20  ITE] to test to 
6c80: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
6c90: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
6ca0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
6cb0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
6cc0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f  D].** to test to
6cd0: 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69   see if a file i
6ce0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
6cf0: 62 6c 65 2e 20 20 54 68 65 20 66 69 6c 65 20 63  ble.  The file c
6d00: 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65  an be a .** dire
6d10: 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ctory..** .** SQ
6d20: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
6d30: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
6d40: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
6d50: 62 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  byte for.** the 
6d60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66  output buffers f
6d70: 6f 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20  or xGetTempname 
6d80: 61 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  and xFullPathnam
6d90: 65 2e 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20  e. The exact.** 
6da0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
6db0: 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73  ut buffer is als
6dc0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
6dd0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
6de0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  .** methods. If 
6df0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
6e00: 72 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  r is not large e
6e10: 6e 6f 75 67 68 2c 20 53 51 4c 49 54 45 5f 43 41  nough, SQLITE_CA
6e20: 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64  NTOPEN.** should
6e30: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73   be returned. As
6e40: 20 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64   this is handled
6e50: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
6e60: 72 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  r by SQLite,.** 
6e70: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
6e80: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 76  ons should endev
6e90: 6f 75 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74  our to prevent t
6ea0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a  his by setting .
6eb0: 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ** mxPathname to
6ec0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
6ed0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20  large value..** 
6ee0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
6ef0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
6f00: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
6f10: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
6f20: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
6f30: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
6f50: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
6f60: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
6f70: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
6f80: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
6f90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
6fa0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
6fb0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
6fc0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
6fd0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
6fe0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
6ff0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
7000: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
7010: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
7020: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
7030: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20  ness obtained.  
7040: 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20  The.** xSleep() 
7050: 6d 65 74 68 6f 64 20 63 61 75 73 65 20 74 68 65  method cause the
7060: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
7070: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
7080: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
7090: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
70a0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
70b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
70c0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
70d0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
70e0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
70f0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a  rent date and.**
7100: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
7110: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7120: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
7130: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7140: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
7150: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
7160: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
7170: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
7180: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
7190: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
71a0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
71b0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
71c0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
71d0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
71e0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
71f0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
7200: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
7210: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
7220: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
7230: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
7240: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
7250: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
7260: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7270: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
7280: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
7290: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
72a0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
72b0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
72c0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
72d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
72e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
72f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
7300: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
7310: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
7320: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7330: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
7340: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7350: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
7360: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
7370: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
7380: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
7390: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
73a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  gs);.  int (*xGe
73b0: 74 54 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74  tTempname)(sqlit
73c0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75  e3_vfs*, int nOu
73d0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
73e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
73f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
7400: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
7410: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
7420: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
7430: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
7440: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
7450: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
7460: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
7470: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
7480: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
7490: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
74a0: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
74b0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
74c0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
74d0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
74e0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
74f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
7500: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
7510: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
7520: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
7530: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
7540: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
7550: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
7560: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
7570: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
7580: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
7590: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
75a0: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
75b0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
75c0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
75d0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
75e0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
75f0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
7600: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
7610: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
7620: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
7630: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
7640: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
7650: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7660: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
7670: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
7680: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
7690: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
76a0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
76b0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
76c0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
76d0: 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64 20  ine.** the kind 
76e0: 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  of what kind of 
76f0: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
7700: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
7710: 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  s.** looking for
7720: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
7730: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
7740: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
7750: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
7760: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
7770: 66 69 6c 65 20 65 78 69 73 74 73 2e 20 20 57 69  file exists.  Wi
7780: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
7790: 5f 52 45 41 44 57 52 49 54 45 2c 0a 2a 2a 20 74  _READWRITE,.** t
77a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
77b0: 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  d checks to see 
77c0: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  if the file is b
77d0: 6f 74 68 20 72 65 61 64 61 62 6c 65 0a 2a 2a 20  oth readable.** 
77e0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20 57  and writable.  W
77f0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
7800: 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65  S_READ the xAcce
7810: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
7820: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
7830: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
7840: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
7850: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
7860: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
7870: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
7880: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
7890: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
78a0: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
78b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
78c0: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
78d0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
78e0: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Codes.**.** This
78f0: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
7900: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
7910: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
7920: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
7930: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
7940: 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64  feature..** By d
7950: 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41  efault, SQLite A
7960: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
7970: 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32  rn one of only 2
7980: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
7990: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
79a0: 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65   codes].  When e
79b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
79c0: 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  odes.** are enab
79d0: 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  led by this rout
79e0: 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69  ine, the repetoi
79f0: 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64  re of result cod
7a00: 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63  es can be.** muc
7a10: 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e  h larger and can
7a20: 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f   (hopefully) pro
7a30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
7a40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
7a50: 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61 75 73  * about the caus
7a60: 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  e of an error..*
7a70: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
7a80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f  argument is a bo
7a90: 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74  olean value that
7aa0: 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20   turns extended 
7ab0: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
7ac0: 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74  on and off.  Ext
7ad0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
7ae0: 65 73 20 61 72 65 20 6f 66 66 20 62 79 20 64 65  es are off by de
7af0: 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63  fault for.** bac
7b00: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
7b10: 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
7b20: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
7b30: 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
7b40: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
7b50: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
7b60: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
7b70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7b80: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
7b90: 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  d.**.** Each ent
7ba0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
7bb0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
7bc0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
7bd0: 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20   integer key.** 
7be0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
7bf0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
7c00: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
7c10: 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  e as an undeclar
7c20: 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d  ed.** column nam
7c30: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
7c40: 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74  r _ROWID_.  If t
7c50: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
7c60: 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65  olumn of.** type
7c70: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
7c80: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
7c90: 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72  olumn is another
7ca0: 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68   an alias for th
7cb0: 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a  e.** rowid..**.*
7cc0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
7cd0: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
7ce0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
7cf0: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49  ent successful I
7d00: 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20 74 68  NSERT into.** th
7d10: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
7d20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
7d30: 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e 20 69 6e  nection given in
7d40: 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 61   the first .** a
7d50: 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20  rgument.  If no 
7d60: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72  successful inser
7d70: 74 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ts have ever occ
7d80: 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61  urred on this da
7d90: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
7da0: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
7db0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
7dc0: 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72   an INSERT occur
7dd0: 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
7de0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77  er, then the row
7df0: 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73  id of the.** ins
7e00: 65 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74  erted row is ret
7e10: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
7e20: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
7e30: 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20   the trigger.** 
7e40: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74  is running.  But
7e50: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
7e60: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
7e70: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
7e80: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
7e90: 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74  ine reverts to t
7ea0: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
7eb0: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
7ec0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72  e.** trigger fir
7ed0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53  ed..**.** An INS
7ee0: 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64  ERT that fails d
7ef0: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
7f00: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
7f10: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
7f20: 66 75 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64  ful insert and d
7f30: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
7f40: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
7f50: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
7f60: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
7f70: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
7f80: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
7f90: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
7fa0: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
7fb0: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
7fc0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
7fd0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
7fe0: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
7ff0: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
8000: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
8010: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
8020: 41 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  ACE .** encounte
8030: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
8040: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
8050: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
8060: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
8070: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
8080: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
8090: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
80a0: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
80b0: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
80c0: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
80d0: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
80e0: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
80f0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
8100: 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
8110: 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
8120: 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20  read does a new 
8130: 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61  insert on the sa
8140: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
8150: 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
8160: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
8170: 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
8180: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
8190: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a  t insert rowid,.
81a0: 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
81b0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
81c0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
81d0: 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65  fined..*/.sqlite
81e0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
81f0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
8200: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
8210: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
8220: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
8230: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
8240: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
8250: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
8260: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
8270: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
8280: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72  e changed.** (or
8290: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
82a0: 65 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73  eted) by the mos
82b0: 74 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61  t recent SQL sta
82c0: 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a  tement.  Only.**
82d0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
82e0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
82f0: 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45  fied by the INSE
8300: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a  RT, UPDATE, or.*
8310: 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
8320: 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
8330: 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
8340: 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
8350: 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74  triggers are not
8360: 20 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74   counted.  Use t
8370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
8380: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
8390: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
83a0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
83b0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
83c0: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
83d0: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
83e0: 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20  s..**.** Within 
83f0: 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
8400: 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74  igger, the sqlit
8410: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
8420: 65 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a  erface can be.**
8430: 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
8440: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
8450: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
8460: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
8470: 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
8480: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
8490: 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
84a0: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
84b0: 66 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  f the trigger..*
84c0: 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73  *.** All changes
84d0: 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76   are counted, ev
84e0: 65 6e 20 69 66 20 74 68 65 79 20 77 65 72 65 20  en if they were 
84f0: 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20  later undone by 
8500: 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72  a.** ROLLBACK or
8510: 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c   ABORT.  Except,
8520: 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61   changes associa
8530: 74 65 64 20 77 69 74 68 20 63 72 65 61 74 69 6e  ted with creatin
8540: 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e  g and.** droppin
8550: 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  g tables are not
8560: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
8570: 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e  If a callback in
8580: 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65  vokes [sqlite3_e
8590: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
85a0: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
85b0: 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20  sively,.** then 
85c0: 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74  the changes in t
85d0: 68 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73  he inner, recurs
85e0: 69 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75  ive call are cou
85f0: 6e 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a  nted together.**
8600: 20 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65   with the change
8610: 73 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63  s in the outer c
8620: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  all..**.** SQLit
8630: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
8640: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
8650: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
8660: 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
8670: 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
8680: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
8690: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
86a0: 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
86b0: 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
86c0: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
86d0: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
86e0: 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
86f0: 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
8700: 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f  use of.** this o
8710: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
8720: 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f   change count fo
8730: 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  r "DELETE FROM t
8740: 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a  able" will be.**
8750: 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73   zero regardless
8760: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
8770: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
8780: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  were originally 
8790: 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e  in the.** table.
87a0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
87b0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
87c0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
87d0: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
87e0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
87f0: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
8800: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ead..**.** If an
8810: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b  other thread mak
8820: 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
8830: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
8840: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
8850: 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
8860: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
8870: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
8880: 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
8890: 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
88a0: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
88b0: 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
88c0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
88d0: 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
88e0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
88f0: 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ied.***.** This 
8900: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
8910: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
8920: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
8930: 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d  t have been.** m
8940: 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52  odified by INSER
8950: 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
8960: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73  ETE statements s
8970: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
8980: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20  e handle.** was 
8990: 6f 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63  opened. This inc
89a0: 6c 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e  ludes UPDATE, IN
89b0: 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20  SERT and DELETE 
89c0: 73 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75  statements execu
89d0: 74 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ted.** as part o
89e0: 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
89f0: 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20  ms. All changes 
8a00: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
8a10: 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74  oon as the.** st
8a20: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
8a30: 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
8a40: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
8a50: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
8a60: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  is.** passed to 
8a70: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
8a80: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
8a90: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
8aa0: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
8ab0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29  sqlite3_change()
8ac0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
8ad0: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
8ae0: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
8af0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
8b00: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
8b10: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
8b20: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
8b30: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
8b40: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
8b50: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
8b60: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
8b70: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
8b80: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
8b90: 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65  s form the table
8ba0: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a  .)  Because of.*
8bb0: 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74  * this optimizat
8bc0: 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20  ion, the change 
8bd0: 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54  count for "DELET
8be0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
8bf0: 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65  ll be.** zero re
8c00: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
8c10: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
8c20: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
8c30: 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a  ginally in the.*
8c40: 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20  * table. To get 
8c50: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
8c60: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
8c70: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
8c80: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
8c90: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
8ca0: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
8cb0: 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
8cc0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
8cd0: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
8ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8cf0: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73  on.** while this
8d00: 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
8d10: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74  ing then the ret
8d20: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
8d30: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20  s routine.** is 
8d40: 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
8d50: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
8d60: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
8d70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8d80: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
8d90: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
8da0: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  ry.**.** This fu
8db0: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
8dc0: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
8dd0: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
8de0: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
8df0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
8e00: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
8e10: 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
8e20: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
8e30: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
8e40: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
8e50: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
8e60: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
8e70: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
8e80: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
8e90: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
8ea0: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
8eb0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
8ec0: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
8ed0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
8ee0: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
8ef0: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
8f00: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
8f10: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
8f20: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
8f30: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
8f40: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
8f50: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
8f60: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
8f70: 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  h a database con
8f80: 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20  nection that.** 
8f90: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
8fa0: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
8fb0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
8fc0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
8fd0: 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72 61  ** The SQL opera
8fe0: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
8ff0: 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
9000: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
9010: 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 61  ERRUPT]..** If a
9020: 6e 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f 70  n interrupted op
9030: 65 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20 75  eration was an u
9040: 70 64 61 74 65 20 74 68 61 74 20 69 73 20 69 6e  pdate that is in
9050: 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  side an.** expli
9060: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
9070: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
9080: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c   transaction wil
9090: 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62  l be rolled.** b
90a0: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
90b0: 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  y..*/.void sqlit
90c0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
90d0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
90e0: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
90f0: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
9100: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
9110: 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  te.**.** These f
9120: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
9130: 74 72 75 65 20 69 66 20 74 68 65 20 67 69 76 65  true if the give
9140: 6e 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63  n input string c
9150: 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65 20  omprises.** one 
9160: 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65  or more complete
9170: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
9180: 20 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33   For the sqlite3
9190: 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c 6c  _complete() call
91a0: 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74  ,.** the paramet
91b0: 65 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75 6c  er must be a nul
91c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
91d0: 38 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a  8 string. For.**
91e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
91f0: 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65 72  e16(), a nul-ter
9200: 6d 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20  minated machine 
9210: 62 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31  byte order UTF-1
9220: 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72  6 string.** is r
9230: 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
9240: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
9250: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
9260: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
9270: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
9280: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
9290: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 66 6f   entered text fo
92a0: 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rms one or more 
92b0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
92c0: 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69 66  tements or.** if
92d0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
92e0: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
92f0: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 73  re sending the s
9300: 74 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a  tatements into.*
9310: 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
9320: 73 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72 69  sing. The algori
9330: 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20  thm is simple.  
9340: 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74 20  If the .** last 
9350: 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61 6e  token other than
9360: 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d 6d   spaces and comm
9370: 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f  ents is a semico
9380: 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e  lon, then return
9390: 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74 75   .** true.  Actu
93a0: 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72 69  ally, the algori
93b0: 74 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65 20  thm is a little 
93c0: 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
93d0: 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69 6e   than that.** in
93e0: 20 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20 77   order to deal w
93f0: 69 74 68 20 74 72 69 67 67 65 72 73 2c 20 62 75  ith triggers, bu
9400: 74 20 74 68 65 20 62 61 73 69 63 20 69 64 65 61  t the basic idea
9410: 20 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20 74   is the same:  t
9420: 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
9430: 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20  is not complete 
9440: 75 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20 69  unless it ends i
9450: 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a  n a semicolon..*
9460: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
9470: 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
9480: 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
9490: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
94a0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
94b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
94c0: 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
94d0: 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
94e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
94f0: 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ors.**.** This r
9500: 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65  outine identifie
9510: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
9520: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
9530: 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
9540: 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d  henever an attem
9550: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
9560: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
9570: 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f  ble .** that ano
9580: 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70  ther thread or p
9590: 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
95a0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  d..** If the bus
95b0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
95c0: 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
95d0: 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f  _BUSY].** (or so
95e0: 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45 5f  metimes [SQLITE_
95f0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a  IOERR_BLOCKED]).
9600: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
9610: 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
9620: 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
9630: 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65   lock..** If the
9640: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
9650: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
9660: 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b   the.** callback
9670: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
9680: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
9690: 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72  nts.  The.** fir
96a0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
96b0: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  he handler is a 
96c0: 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
96d0: 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
96e0: 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
96f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
9700: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73   routine.  The s
9710: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
9720: 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
9730: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
9740: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
9750: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
9760: 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
9770: 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
9780: 6e 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68 65  ng event. If the
9790: 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
97a0: 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
97b0: 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
97c0: 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
97d0: 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
97e0: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
97f0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
9800: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
9810: 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
9820: 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
9830: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
9840: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
9850: 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20 69  nother attempt i
9860: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
9870: 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66  he.** database f
9880: 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
9890: 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
98a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
98b0: 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
98c0: 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
98d0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a  guarantee that.*
98e0: 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  * it will be inv
98f0: 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20  oked when there 
9900: 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
9910: 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  on..** If SQLite
9920: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
9930: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
9940: 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  sy handler could
9950: 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20   result in.** a 
9960: 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
9970: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
9980: 5f 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 0a  _BUSY] instead..
9990: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
99a0: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
99b0: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
99c0: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
99d0: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
99e0: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
99f0: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
9a00: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
9a10: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
9a20: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
9a30: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
9a40: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
9a50: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
9a60: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
9a70: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
9a80: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
9a90: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
9aa0: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
9ab0: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
9ac0: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
9ad0: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
9ae0: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
9af0: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
9b00: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
9b10: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
9b20: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
9b30: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
9b40: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
9b50: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
9b60: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
9b70: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
9b80: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
9b90: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
9ba0: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
9bb0: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
9bc0: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
9bd0: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
9be0: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
9bf0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
9c00: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
9c10: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
9c20: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
9c30: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
9c40: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
9c50: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
9c60: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
9c70: 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a 2a  _BLOCKED] when.*
9c80: 2a 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  * SQLite is in t
9c90: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
9ca0: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
9cb0: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
9cc0: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
9cd0: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
9ce0: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
9cf0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
9d00: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
9d10: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
9d20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9d30: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
9d40: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
9d50: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
9d60: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
9d70: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
9d80: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
9d90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9da0: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
9db0: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
9dc0: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
9dd0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
9de0: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
9df0: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
9e00: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
9e10: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
9e20: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
9e30: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
9e40: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
9e50: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
9e60: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
9e70: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
9e80: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
9e90: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
9ea0: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
9eb0: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
9ec0: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
9ed0: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
9ee0: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
9ef0: 61 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a 2a  anges. See the.*
9f00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
9f10: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
9f20: 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
9f30: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
9f40: 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
9f50: 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
9f60: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
9f70: 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
9f80: 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
9f90: 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
9fa0: 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a  important..**..*
9fb0: 2a 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65  * Sqlite is re-e
9fc0: 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62  ntrant, so the b
9fd0: 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  usy handler may 
9fe0: 73 74 61 72 74 20 61 20 6e 65 77 20 71 75 65 72  start a new quer
9ff0: 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f  y. .** (It is no
a000: 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f  t clear why anyo
a010: 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77  ne would every w
a020: 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20  ant to do this, 
a030: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c  but it.** is all
a040: 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e  owed, in theory.
a050: 29 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20  )  But the busy 
a060: 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20  handler may not 
a070: 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74  close the.** dat
a080: 61 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20  abase.  Closing 
a090: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
a0a0: 6d 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  m a busy handler
a0b0: 20 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a   will delete .**
a0c0: 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
a0d0: 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20   out from under 
a0e0: 74 68 65 20 65 78 65 63 75 74 69 6e 67 20 71 75  the executing qu
a0f0: 65 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a  ery and will .**
a100: 20 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74   probably result
a110: 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
a120: 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
a130: 72 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e  r runtime error.
a140: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
a150: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
a160: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
a170: 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20  efined for each 
a180: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
a190: 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67  ection.  Setting
a1a0: 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
a1b0: 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70  ler clears any p
a1c0: 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20  revious one..** 
a1d0: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
a1e0: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
a1f0: 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20  timeout()] will 
a200: 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
a210: 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  r.** the busy ha
a220: 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ndler..**.** Whe
a230: 6e 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b  n operating in [
a240: 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
a250: 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68  hared_cache | sh
a260: 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
a270: 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67  ,.** only a sing
a280: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
a290: 63 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66  can be defined f
a2a0: 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65  or each database
a2b0: 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20   file..** So if 
a2c0: 74 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e  two database con
a2d0: 6e 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61  nections share a
a2e0: 20 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74   single cache, t
a2f0: 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20  hen changing.** 
a300: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
a310: 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69   on one connecti
a320: 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61  on will also cha
a330: 6e 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  nge the busy.** 
a340: 68 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f  handler in the o
a350: 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  ther connection.
a360: 20 20 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c    The busy handl
a370: 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  er is invoked.**
a380: 20 69 6e 20 74 68 65 20 74 68 72 65 61 64 20 74   in the thread t
a390: 68 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20  hat was running 
a3a0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
a3b0: 42 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a 2f  BUSY was hit..*/
a3c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
a3d0: 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
a3e0: 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
a3f0: 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
a400: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a410: 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
a420: 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  ut.**.** This ro
a430: 75 74 69 6e 65 20 73 65 74 73 20 61 20 62 75 73  utine sets a bus
a440: 79 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73  y handler that s
a450: 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c  leeps for a whil
a460: 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c  e when a.** tabl
a470: 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68  e is locked.  Th
a480: 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73  e handler will s
a490: 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
a4a0: 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74  mes until .** at
a4b0: 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
a4c0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
a4d0: 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64  ping have been d
a4e0: 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22  one.  After.** "
a4f0: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
a500: 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
a510: 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
a520: 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
a530: 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
a540: 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
a550: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
a560: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
a570: 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
a580: 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
a590: 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
a5a0: 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
a5b0: 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
a5c0: 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
a5d0: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
a5e0: 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
a5f0: 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
a600: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
a610: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
a620: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
a630: 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65  tion.  If anothe
a640: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  r busy handler w
a650: 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20  as defined  .** 
a660: 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
a670: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
a680: 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
a690: 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
a6a0: 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
a6b0: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
a6c0: 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eared..*/.int sq
a6d0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
a6e0: 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
a6f0: 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
a700: 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
a710: 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
a720: 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
a730: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20  **.** This next 
a740: 72 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e  routine is a con
a750: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
a760: 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33   around [sqlite3
a770: 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73  _exec()]..** Ins
a780: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
a790: 20 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64   a user-supplied
a7a0: 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61   callback for ea
a7b0: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a  ch row of the.**
a7c0: 20 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f   result, this ro
a7d0: 75 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20  utine remembers 
a7e0: 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20  each row of the 
a7f0: 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79  result in memory
a800: 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
a810: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
a820: 63 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72  c()], then retur
a830: 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65  ns all of the re
a840: 73 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a  sult after the.*
a850: 2a 20 71 75 65 72 79 20 68 61 73 20 66 69 6e 69  * query has fini
a860: 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20  shed. .**.** As 
a870: 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70  an example, supp
a880: 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 72 65  ose the query re
a890: 73 75 6c 74 20 77 68 65 72 65 20 74 68 69 73 20  sult where this 
a8a0: 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  table:.**.** <bl
a8b0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
a8c0: 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
a8d0: 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
a8e0: 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
a8f0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
a900: 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
a910: 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
a920: 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
a930: 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
a940: 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
a950: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
a960: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ote>.**.** If th
a970: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 77  e 3rd argument w
a980: 65 72 65 20 26 61 7a 52 65 73 75 6c 74 20 74 68  ere &azResult th
a990: 65 6e 20 61 66 74 65 72 20 74 68 65 20 66 75 6e  en after the fun
a9a0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a  ction returns.**
a9b0: 20 61 7a 52 65 73 75 6c 74 20 77 69 6c 6c 20 63   azResult will c
a9c0: 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  ontain the follo
a9d0: 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a 2a 2a  wing data:.**.**
a9e0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
a9f0: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
aa00: 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
aa10: 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
aa20: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
aa30: 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
aa40: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
aa50: 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
aa60: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
aa70: 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
aa80: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
aa90: 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
aaa0: 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
aab0: 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
aac0: 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
aad0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
aae0: 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
aaf0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
ab00: 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
ab10: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
ab20: 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65  te>.**.** Notice
ab30: 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 61   that there is a
ab40: 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20 64  n extra row of d
ab50: 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ata containing t
ab60: 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61  he column.** hea
ab70: 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20 2a  ders.  But the *
ab80: 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c 75  nrow return valu
ab90: 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a  e is still 3.  *
aba0: 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65  ncolumn is.** se
abb0: 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65  t to 2.  In gene
abc0: 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ral, the number 
abd0: 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72 74  of values insert
abe0: 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74  ed into azResult
abf0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e  .** will be ((*n
ac00: 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c  row) + 1)*(*ncol
ac10: 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  umn)..**.** Afte
ac20: 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  r the calling fu
ac30: 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  nction has finis
ac40: 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65  hed using the re
ac50: 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20  sult, it should 
ac60: 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65 73  .** pass the res
ac70: 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ult data pointer
ac80: 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
ac90: 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
aca0: 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65  r to .** release
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
acc0: 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20   was malloc-ed. 
acd0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ace0: 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  way the .** [sql
acf0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
ad00: 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c  appens, the call
ad10: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
ad20: 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
ad30: 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  l .** [sqlite3_f
ad40: 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
ad50: 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f    Only [sqlite3_
ad60: 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
ad70: 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
ad80: 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20   .** the memory 
ad90: 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
ada0: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ely..**.** The r
adb0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
adc0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
add0: 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d 20  he same as from 
ade0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
adf0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
ae00: 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
ae10: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
ae20: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
ae30: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
ae40: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
ae50: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
ae60: 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20 20  e executed */.  
ae70: 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c  char ***resultp,
ae80: 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74         /* Result
ae90: 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63 68   written to a ch
aea0: 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68 69  ar *[]  that thi
aeb0: 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20  s points to */. 
aec0: 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20   int *nrow,     
aed0: 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
aee0: 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
aef0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
af00: 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c  .  int *ncolumn,
af10: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
af20: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
af30: 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
af40: 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  re */.  char **e
af50: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 2f  rrmsg          /
af60: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
af70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
af80: 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
af90: 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
afa0: 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
afb0: 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
afc0: 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
afd0: 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
afe0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
aff0: 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20   are workalikes 
b000: 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
b010: 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
b020: 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
b030: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
b040: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rary..**.** The 
b050: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
b060: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
b070: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
b080: 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
b090: 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
b0a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
b0b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
b0c0: 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
b0d0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
b0e0: 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
b0f0: 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
b100: 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
b110: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
b120: 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
b130: 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
b140: 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
b150: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
b160: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
b170: 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
b180: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
b190: 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
b1a0: 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
b1b0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
b1c0: 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
b1d0: 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
b1e0: 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
b1f0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
b200: 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
b210: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
b220: 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
b230: 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
b240: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
b250: 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
b260: 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
b270: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74   parameter.  Not
b280: 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
b290: 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
b2a0: 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
b2b0: 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
b2c0: 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
b2d0: 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
b2e0: 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
b2f0: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
b300: 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
b310: 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
b320: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
b330: 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
b340: 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
b350: 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
b360: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
b370: 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
b380: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
b390: 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
b3a0: 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
b3b0: 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
b3c0: 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
b3d0: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
b3e0: 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
b3f0: 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
b400: 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
b410: 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
b420: 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
b430: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
b440: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
b450: 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
b460: 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
b470: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
b480: 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
b490: 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
b4a0: 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
b4b0: 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
b4c0: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
b4d0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
b4e0: 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
b4f0: 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
b500: 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
b510: 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
b520: 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
b530: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
b540: 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
b550: 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
b560: 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
b570: 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
b580: 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
b590: 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
b5a0: 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
b5b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
b5c0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
b5d0: 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
b5e0: 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
b5f0: 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
b600: 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
b610: 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
b620: 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
b630: 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
b640: 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
b650: 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  f formatting opt
b660: 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
b670: 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
b680: 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
b690: 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
b6a0: 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
b6b0: 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
b6c0: 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
b6d0: 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
b6e0: 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
b6f0: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
b700: 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
b710: 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
b720: 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
b730: 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
b740: 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
b750: 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
b760: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
b770: 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
b780: 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
b790: 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
b7a0: 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
b7b0: 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
b7c0: 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
b7d0: 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
b7e0: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
b7f0: 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72  ple, so some str
b800: 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e  ing variable con
b810: 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
b820: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
b830: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
b840: 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
b850: 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
b860: 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
b870: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
b880: 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
b890: 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
b8a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
b8b0: 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
b8c0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
b8d0: 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
b8e0: 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
b8f0: 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
b900: 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
b910: 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
b920: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
b930: 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
b940: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
b950: 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
b960: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
b970: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
b980: 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
b990: 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
b9a0: 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
b9b0: 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
b9c0: 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
b9d0: 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
b9e0: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
b9f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
ba00: 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
ba10: 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
ba20: 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
ba30: 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
ba40: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ba50: 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
ba60: 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
ba70: 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
ba80: 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
ba90: 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
baa0: 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
bab0: 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
bac0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
bad0: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
bae0: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
baf0: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
bb00: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
bb10: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
bb20: 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
bb30: 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
bb40: 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
bb50: 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
bb60: 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61  u.** should alwa
bb70: 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
bb80: 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
bb90: 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
bba0: 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69   a string .** li
bbb0: 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
bbc0: 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
bbd0: 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
bbe0: 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
bbf0: 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
bc00: 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
bc10: 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
bc20: 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65  ring.  Or if the
bc30: 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
bc40: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69  e argument.** li
bc50: 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
bc60: 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
bc70: 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
bc80: 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69  ULL" (without si
bc90: 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20  ngle.** quotes) 
bca0: 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
bcb0: 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20  %Q option.  So, 
bcc0: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
bcd0: 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
bce0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
bcf0: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
bd00: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
bd10: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
bd20: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
bd30: 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
bd40: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
bd50: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
bd60: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
bd70: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
bd80: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
bd90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
bda0: 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
bdb0: 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
bdc0: 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
bdd0: 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
bde0: 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
bdf0: 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
be00: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66  **.** The "%z" f
be20: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
be30: 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
be40: 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68  ike "%s" with th
be50: 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
be60: 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
be70: 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
be80: 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
be90: 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
bea0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
beb0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
bec0: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
bed0: 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
bee0: 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
bef0: 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
bf00: 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
bf10: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
bf20: 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
bf30: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
bf40: 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
bf50: 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
bf60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
bf70: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
bf80: 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
bf90: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
bfa0: 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
bfb0: 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
bfc0: 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
bfd0: 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
bfe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
bff0: 73 2e 20 28 53 65 65 20 74 68 65 20 65 78 63 65  s. (See the exce
c000: 70 74 69 6f 6e 20 62 65 6c 6f 77 2e 29 0a 2a 2a  ption below.).**
c010: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
c020: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
c030: 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20  * of the memory 
c040: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
c050: 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61  stem uses the ma
c060: 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
c070: 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20  ).** and free() 
c080: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
c090: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c0a0: 72 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  ry.  However, if
c0b0: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63   .** SQLite is c
c0c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
c0d0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65   following C pre
c0e0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
c0f0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
c100: 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  e> SQLITE_MEMORY
c110: 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
c120: 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
c130: 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e 4e  *.** where <i>NN
c140: 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74 65  N</i> is an inte
c150: 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ger, then SQLite
c160: 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
c170: 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74 20  .** array of at 
c180: 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  least <i>NNN</i>
c190: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
c1a0: 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72 61  nd use that arra
c1b0: 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  y.** for all of 
c1c0: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
c1d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
c1e0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  eds..**.** In SQ
c1f0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
c200: 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
c210: 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
c220: 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
c230: 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
c240: 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
c250: 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
c260: 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
c270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
c280: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
c290: 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
c2a0: 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
c2b0: 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
c2c0: 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
c2d0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c2e0: 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
c2f0: 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  e.** used..**.**
c300: 20 3c 62 3e 45 78 63 65 70 74 69 6f 6e 3a 3c 2f   <b>Exception:</
c310: 62 3e 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f  b> The windows O
c320: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
c330: 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
c340: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
c350: 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
c360: 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
c370: 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
c380: 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
c390: 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
c3a0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
c3b0: 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
c3c0: 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
c3d0: 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
c3e0: 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a  cular windows.**
c3f0: 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
c400: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
c410: 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
c420: 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
c430: 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
c440: 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
c450: 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
c460: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
c470: 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
c480: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 76 6f  TE_NOMEM]..*/.vo
c490: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
c4a0: 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
c4b0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
c4c0: 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
c4d0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
c4e0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
c4f0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
c500: 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
c510: 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 64 69  cs.**.** In addi
c520: 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 73 69  tion to the basi
c530: 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 74 69  c three allocati
c540: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20  on routines .** 
c550: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c560: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
c570: 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
c580: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
c590: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
c5a0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
c5b0: 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  m included with 
c5c0: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 73 6f  the SQLite.** so
c5d0: 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 20 74  urces provides t
c5e0: 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 68  he interfaces sh
c5f0: 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a 2a 2a  own below..**.**
c600: 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 74 68   The first of th
c610: 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
c620: 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 6d 6f   returns the amo
c630: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 0a 2a  unt of memory .*
c640: 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  * currently outs
c650: 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
c660: 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
c670: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  .  The second.**
c680: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 61 72   returns the lar
c690: 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f  gest instantaneo
c6a0: 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f 75 74  us amount of out
c6b0: 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 6d 6f  standing.** memo
c6c0: 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 61 74  ry.  The highwat
c6d0: 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
c6e0: 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
c6f0: 20 69 73 0a 2a 2a 20 74 72 75 65 2e 0a 2a 2a 0a   is.** true..**.
c700: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
c710: 75 72 6e 65 64 20 6d 61 79 20 6f 72 20 6d 61 79  urned may or may
c720: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 61 6c 6c   not include all
c730: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 76 65 72 68  ocation.** overh
c740: 65 61 64 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  ead, depending o
c750: 6e 20 77 68 69 63 68 20 62 75 69 6c 74 2d 69 6e  n which built-in
c760: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c770: 72 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  r.** implementat
c780: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a  ion is used..*/.
c790: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
c7a0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
c7b0: 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
c7c0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
c7d0: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
c7e0: 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
c7f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c800: 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
c810: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
c820: 62 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  backs.***.** Thi
c830: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
c840: 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
c850: 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74   callback with t
c860: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
c870: 79 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68  y.  .** The auth
c880: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
c890: 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
c8a0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
c8b0: 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
c8c0: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
c8d0: 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
c8e0: 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
c8f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
c900: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
c910: 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
c920: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
c930: 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
c940: 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
c950: 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
c960: 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
c970: 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
c980: 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
c990: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
c9a0: 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
c9b0: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
c9c0: 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
c9d0: 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
c9e0: 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
c9f0: 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
ca00: 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
ca10: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c  ld.** return SQL
ca20: 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20  ITE_OK to allow 
ca30: 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
ca40: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
ca50: 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
ca60: 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
ca70: 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
ca80: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
ca90: 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
caa0: 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
cab0: 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
cac0: 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
cad0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
cae0: 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
caf0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a  ith an error.  .
cb00: 2a 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20  **.** Depending 
cb10: 6f 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74  on the action, t
cb20: 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
cb30: 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44  E] and [SQLITE_D
cb40: 45 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63  ENY] return.** c
cb50: 6f 64 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20  odes might mean 
cb60: 73 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72  something differ
cb70: 65 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68  ent or they migh
cb80: 74 20 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a  t mean the same.
cb90: 2a 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68  ** thing.  If th
cba0: 65 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72  e action is, for
cbb0: 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72   example, to per
cbc0: 66 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70  form a delete op
cbd0: 65 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20  ertion,.** then 
cbe0: 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
cbf0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  and [SQLITE_DENY
cc00: 5d 20 62 6f 74 68 20 63 61 75 73 65 20 74 68 65  ] both cause the
cc10: 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
cc20: 6c 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69  lation.** to fai
cc30: 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  l with an error.
cc40: 20 20 42 75 74 20 69 66 20 74 68 65 20 61 63 74    But if the act
cc50: 69 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61  ion is to read a
cc60: 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
cc70: 0a 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69  .** from a speci
cc80: 66 69 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20  fic table, then 
cc90: 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69  [SQLITE_DENY] wi
cca0: 6c 6c 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  ll cause the ent
ccb0: 69 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ire.** statement
ccc0: 20 74 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51   to fail but [SQ
ccd0: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c  LITE_IGNORE] wil
cce0: 6c 20 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76  l cause a NULL v
ccf0: 61 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65  alue to be.** re
cd00: 61 64 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ad instead of th
cd10: 65 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20  e actual column 
cd20: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
cd30: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
cd40: 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
cd50: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
cd60: 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
cd70: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
cd80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
cd90: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
cda0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68  interface..** Th
cdb0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
cdc0: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
cdd0: 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
cde0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50   .** [SQLITE_COP
cdf0: 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
ce00: 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
ce10: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
ce20: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61  ction.** to be a
ce30: 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
ce40: 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e  available action
ce50: 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53   codes are.** [S
ce60: 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63  QLITE_COPY | doc
ce70: 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74 65  umented separate
ce80: 6c 79 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20  ly].  The third 
ce90: 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a  through sixth.**
cea0: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
ceb0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
cec0: 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
ced0: 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
cee0: 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
cef0: 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
cf00: 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
cf10: 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
cf20: 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70  r is used when p
cf30: 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61  reparing SQL sta
cf40: 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
cf50: 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75  untrusted.** sou
cf60: 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
cf70: 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
cf80: 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72  ements do not tr
cf90: 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
cfa0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72  .** that they ar
cfb0: 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
cfc0: 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
cfd0: 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ey do not try to
cfe0: 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69  .** execute mali
cff0: 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
d000: 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
d010: 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
d020: 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
d030: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
d040: 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
d050: 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
d060: 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
d070: 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
d080: 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
d090: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
d0a0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
d0b0: 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
d0c0: 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
d0d0: 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
d0e0: 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
d0f0: 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
d100: 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
d110: 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
d120: 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
d130: 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
d140: 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68  eing prepared th
d150: 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  at disallows eve
d160: 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70  rything.** excep
d170: 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  t SELECT stateme
d180: 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c  nts.  .**.** Onl
d190: 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
d1a0: 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
d1b0: 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
d1c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
d1d0: 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
d1e0: 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
d1f0: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
d200: 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
d210: 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
d220: 2e 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  .  A NULL author
d230: 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
d240: 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
d250: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
d260: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65  invoked.  The de
d270: 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
d280: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
d290: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
d2a0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
d2b0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
d2c0: 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71  y during .** [sq
d2d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
d2e0: 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
d2f0: 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
d300: 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
d310: 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
d320: 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
d330: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
d340: 70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  p()]..*/.int sql
d350: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
d360: 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
d370: 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
d380: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
d390: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
d3a0: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
d3b0: 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
d3c0: 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
d3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d3e0: 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
d3f0: 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
d400: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
d410: 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
d420: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
d430: 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
d440: 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
d450: 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
d460: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
d470: 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
d480: 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
d490: 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
d4a0: 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
d4b0: 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
d4c0: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
d4d0: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
d4e0: 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
d4f0: 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
d500: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
d510: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
d520: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d530: 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
d540: 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
d550: 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
d560: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
d570: 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
d580: 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
d590: 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
d5a0: 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
d5b0: 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
d5c0: 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
d5d0: 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
d5e0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
d5f0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
d600: 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
d610: 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
d620: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
d630: 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
d640: 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20  d to authorizer 
d650: 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
d660: 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
d670: 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
d680: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
d690: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
d6a0: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
d6b0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
d6c0: 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
d6d0: 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
d6e0: 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
d6f0: 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
d700: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
d710: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
d720: 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
d730: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
d740: 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
d750: 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
d760: 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
d770: 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68  s to be .** auth
d780: 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
d790: 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
d7a0: 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
d7b0: 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63  rization callbac
d7c0: 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  k.** function wi
d7d0: 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
d7e0: 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
d7f0: 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
d800: 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
d810: 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
d820: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
d830: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
d840: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
d850: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
d860: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
d870: 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
d880: 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a  in", "temp", .**
d890: 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
d8a0: 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
d8b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
d8c0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
d8d0: 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
d8e0: 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
d8f0: 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
d900: 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
d910: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
d920: 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
d930: 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
d940: 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
d950: 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
d960: 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  om .** top-level
d970: 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
d980: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d990: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d9a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
d9b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
d9c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
d9e0: 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
d9f0: 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
da00: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
da10: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
da20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
da30: 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
da40: 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
da50: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
da60: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
da70: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
da80: 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
da90: 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
daa0: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
dab0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
dac0: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
dad0: 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
dae0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
daf0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
db00: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
db10: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
db20: 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
db30: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
db40: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
db50: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
db60: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
db70: 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
db80: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
db90: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
dba0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
dbb0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
dbc0: 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
dbd0: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
dbe0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
dbf0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dc00: 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
dc10: 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
dc20: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
dc30: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
dc40: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
dc50: 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
dc60: 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
dc70: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
dc80: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
dc90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dca0: 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
dcb0: 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
dcc0: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
dcd0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
dce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dcf0: 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
dd00: 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
dd10: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
dd20: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
dd30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dd40: 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
dd50: 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
dd60: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
dd70: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
dd80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dd90: 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
dda0: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
ddb0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
ddc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
ddd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
dde0: 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
ddf0: 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
de00: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
de10: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
de20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
de30: 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
de40: 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
de50: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
de60: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
de70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
de80: 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
de90: 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
dea0: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
deb0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
dec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
ded0: 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
dee0: 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
def0: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
df00: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
df10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
df20: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
df30: 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
df40: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
df50: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
df60: 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
df70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
df80: 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
df90: 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
dfa0: 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
dfb0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
dfc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
dfd0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
dfe0: 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
dff0: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
e000: 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
e010: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
e020: 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
e030: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
e040: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e050: 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
e060: 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
e070: 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
e080: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
e090: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e0a0: 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
e0b0: 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
e0c0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
e0d0: 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
e0e0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e0f0: 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
e100: 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
e110: 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
e120: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e130: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e140: 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
e150: 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
e160: 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
e170: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
e180: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e190: 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
e1a0: 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
e1b0: 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
e1c0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e1d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e1e0: 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
e1f0: 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
e200: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
e210: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
e220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e230: 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
e240: 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
e250: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
e260: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e280: 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
e290: 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
e2a0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
e2b0: 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
e2c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
e2d0: 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
e2e0: 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
e2f0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
e300: 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
e310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
e320: 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
e330: 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74     31   /* Funct
e340: 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ion Name   NULL 
e350: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
e370: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
e380: 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
e390: 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
e3a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
e3b0: 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
e3c0: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
e3d0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
e3e0: 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
e3f0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
e400: 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
e410: 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
e420: 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
e430: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
e440: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
e450: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
e460: 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
e470: 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
e480: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
e490: 2a 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b  * at the first [
e4a0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
e4b0: 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69  for the evaluati
e4c0: 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  on of an SQL sta
e4d0: 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63  tement..** The c
e4e0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
e4f0: 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
e500: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
e510: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
e520: 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
e530: 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e  ment finishes an
e540: 64 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e  d includes.** in
e550: 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77  formation on how
e560: 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
e570: 6d 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20  ment ran..**.** 
e580: 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  The sqlite3_prof
e590: 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72  ile() API is cur
e5a0: 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
e5b0: 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
e5c0: 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74  nd.** is subject
e5d0: 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76   to change..*/.v
e5e0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
e5f0: 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
e600: 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
e610: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
e620: 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
e630: 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
e640: 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
e650: 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
e660: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
e670: 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
e680: 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
e690: 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
e6a0: 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
e6b0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
e6c0: 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
e6d0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
e6e0: 20 2d 20 74 68 65 20 70 72 6f 67 72 65 73 73 20   - the progress 
e6f0: 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a  callback - that.
e700: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  ** is invoked pe
e710: 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
e720: 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
e730: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
e740: 5f 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _exec()],.** [sq
e750: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
e760: 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
e770: 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61  able()].  An exa
e780: 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
e790: 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  s .** interface 
e7a0: 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
e7b0: 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
e7c0: 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
e7d0: 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
e7e0: 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  s callback is in
e7f0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
e800: 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d  very N virtual m
e810: 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a  achine opcodes,.
e820: 2a 2a 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ** where N is th
e830: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
e840: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
e850: 6f 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73  on. The progress
e860: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73   callback.** its
e870: 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65  elf is identifie
e880: 64 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61  d by the third a
e890: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
e8a0: 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f  function. The fo
e8b0: 75 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  urth.** argument
e8c0: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
e8d0: 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e  n is a void poin
e8e0: 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
e8f0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e900: 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
e910: 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
e920: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  invoked..**.** I
e930: 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
e940: 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
e950: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
e960: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  or [sqlite3_get_
e970: 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75  table()].** resu
e980: 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
e990: 6e 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e  n N opcodes bein
e9a0: 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e  g executed, then
e9b0: 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a   the progress .*
e9c0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  * callback is ne
e9d0: 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  ver invoked..** 
e9e0: 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** Only a singl
e9f0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
ea00: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
ea10: 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 66   be registered f
ea20: 6f 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20  or each.** open 
ea30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ea40: 69 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c  ion.  Every call
ea50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   to sqlite3_prog
ea60: 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a  ress_handler().*
ea70: 2a 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  * overwrites the
ea80: 20 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   results of the 
ea90: 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a  previous call..*
eaa0: 2a 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20  * To remove the 
eab0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
eac0: 6b 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61  k altogether, pa
ead0: 73 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74  ss NULL as the t
eae0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
eaf0: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
eb00: 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
eb10: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
eb20: 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  k returns a resu
eb30: 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c  lt other than 0,
eb40: 20 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e   then the curren
eb50: 74 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69  t .** query is i
eb60: 6d 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69  mmediately termi
eb70: 6e 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61  nated and any da
eb80: 74 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72  tabase changes r
eb90: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54  olled back..** T
eba0: 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73  he containing [s
ebb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
ebc0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
ebd0: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
ebe0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61  _get_table()] ca
ebf0: 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ll returns SQLIT
ec00: 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54  E_INTERRUPT.   T
ec10: 68 69 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63  his feature.** c
ec20: 61 6e 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  an be used, for 
ec30: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c  example, to impl
ec40: 65 6d 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65  ement the "Cance
ec50: 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a  l" button on a.*
ec60: 2a 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  * progress dialo
ec70: 67 20 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a  g box in a GUI..
ec80: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
ec90: 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
eca0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
ecb0: 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
ecc0: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
ecd0: 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
ece0: 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
ecf0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
ed00: 4f 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20  Open the sqlite 
ed10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 66  database file "f
ed20: 69 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22  ilename".  The "
ed30: 66 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46  filename" is UTF
ed40: 2d 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f  -8.** encoded fo
ed50: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
ed60: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
ed70: 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 55  open_v2()] and U
ed80: 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 0a 2a 2a  TF-16 encoded.**
ed90: 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
eda0: 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
edb0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
edc0: 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  ..** An [sqlite3
edd0: 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65 74  *] handle is ret
ede0: 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
edf0: 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72  even.** if an er
ee00: 72 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20 74  ror occurs. If t
ee10: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
ee20: 70 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74 65  pened (or create
ee30: 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
ee40: 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  .** then [SQLITE
ee50: 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
ee60: 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65  . Otherwise an e
ee70: 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
ee80: 75 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73  urned. The.** [s
ee90: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
eea0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
eeb0: 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e  msg16()]  routin
eec0: 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
eed0: 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
eee0: 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
eef0: 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
ef00: 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
ef10: 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
ef20: 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
ef30: 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
ef40: 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74  F-8 if.** [sqlit
ef50: 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
ef60: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
ef70: 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ] is called and.
ef80: 2a 2a 20 55 54 46 2d 31 36 20 69 66 20 5b 73 71  ** UTF-16 if [sq
ef90: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
efa0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
efb0: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
efc0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
efd0: 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
efe0: 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63   resources assoc
eff0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
f000: 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  e [sqlite3*] han
f010: 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
f020: 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69 6e  leased by passin
f030: 67 20 69 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  g it to.** [sqli
f040: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
f050: 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
f060: 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
f070: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  * The [sqlite3_o
f080: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
f090: 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b  ace works like [
f0a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
f0b0: 65 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 70  except that.** p
f0c0: 72 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64 69  rovides two addi
f0d0: 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
f0e0: 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
f0f0: 20 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 68   control over th
f100: 65 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 73  e.** new databas
f110: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
f120: 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
f130: 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f 66  er can be one of
f140: 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
f150: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f160: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20  EN_READONLY].** 
f170: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f180: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a  EN_READWRITE].**
f190: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f1a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
f1b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
f1c0: 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  EATE].** </ol>.*
f1d0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76  *.** The first v
f1e0: 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64  alue opens the d
f1f0: 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c  atabase read-onl
f200: 79 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  y.  If the datab
f210: 61 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ase does.** not 
f220: 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
f230: 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
f240: 74 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65 63  turned.  The sec
f250: 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73  ond option opens
f260: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
f270: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
f280: 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
f290: 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
f2a0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74   only if.** if t
f2b0: 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
f2c0: 20 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20   protected.  In 
f2d0: 65 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20  either case the 
f2e0: 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
f2f0: 72 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 20 6f  ready.** exist o
f300: 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  r an error is re
f310: 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69  turned.  The thi
f320: 72 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 20  rd option opens 
f330: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
f340: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
f350: 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61  writing and crea
f360: 74 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65  tes it if it doe
f370: 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
f380: 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ist..** The thir
f390: 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68  d options is beh
f3a0: 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
f3b0: 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73  ways used for [s
f3c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
f3d0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  * and [sqlite3_o
f3e0: 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
f3f0: 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
f400: 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
f410: 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a  hen an private.*
f420: 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  * in-memory data
f430: 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20  base is created 
f440: 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
f450: 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
f460: 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ory.** database 
f470: 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
f480: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
f490: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
f4a0: 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
f4b0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
f4c0: 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20   might make use 
f4d0: 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
f4e0: 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  ecial filenames.
f4f0: 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  ** that begin wi
f500: 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
f510: 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65 63  cter.  It is rec
f520: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a  ommended that .*
f530: 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  * when a databas
f540: 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c  e filename reall
f550: 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
f560: 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f  h.** ":" that yo
f570: 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  u prefix the fil
f580: 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
f590: 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20  hname like "./" 
f5a0: 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69  to.** avoid ambi
f5b0: 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
f5c0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
f5d0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
f5e0: 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20   then a private 
f5f0: 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
f600: 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
f610: 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
f620: 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
f630: 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
f640: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
f650: 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
f660: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
f670: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
f680: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
f690: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
f6a0: 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
f6b0: 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
f6c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
f6d0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
f6e0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
f6f0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
f700: 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  m .** interface 
f710: 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74  that the new dat
f720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f730: 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
f740: 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
f750: 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55  arameter is a NU
f760: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
f770: 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
f780: 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a  ite3_vfs].** obj
f790: 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
f7a0: 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69  ** <b>Note to wi
f7b0: 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
f7c0: 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
f7d0: 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
f7e0: 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
f7f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
f800: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
f810: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73  3_open_v2()] mus
f820: 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
f830: 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
f840: 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
f850: 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
f860: 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
f870: 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
f880: 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
f890: 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
f8a0: 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
f8b0: 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
f8c0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  to.** [sqlite3_o
f8d0: 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
f8e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a  e3_open_v2()]..*
f8f0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
f900: 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
f910: 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
f920: 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
f930: 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
f940: 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
f950: 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
f960: 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
f970: 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
f980: 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
f990: 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
f9a0: 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
f9b0: 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
f9c0: 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
f9d0: 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
f9e0: 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
f9f0: 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
fa00: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
fa10: 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
fa20: 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
fa30: 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
fa40: 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
fa50: 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
fa60: 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
fa70: 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
fa80: 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
fa90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
faa0: 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
fab0: 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
fac0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
fad0: 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
fae0: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
faf0: 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
fb00: 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
fb10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fb20: 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
fb30: 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
fb40: 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
fb50: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
fb60: 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
fb70: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
fb80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fb90: 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
fba0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
fbb0: 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
fbc0: 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
fbd0: 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
fbe0: 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
fbf0: 20 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49    If a prior API
fc00: 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74   call failed but
fc10: 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
fc20: 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
fc30: 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
fc40: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
fc50: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a  lite3_errcode().
fc60: 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
fc70: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
fc80: 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
fc90: 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
fca0: 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
fcb0: 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
fcc0: 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
fcd0: 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
fce0: 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20   either UTF8 or 
fcf0: 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65  UTF16 respective
fd00: 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f  ly..** Memory to
fd10: 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
fd20: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
fd30: 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
fd40: 61 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73  ally.  The .** s
fd50: 74 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65  tring may be ove
fd60: 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
fd70: 6c 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65  located by subse
fd80: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53  quent calls to S
fd90: 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61  QLite.** interfa
fda0: 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
fdb0: 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e  .** Calls to man
fdc0: 79 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63  y sqlite3_* func
fdd0: 74 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72  tions set the er
fde0: 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72  ror code and str
fdf0: 69 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ing returned.** 
fe00: 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
fe10: 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
fe20: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20  _errmsg()], and 
fe30: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
fe40: 36 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69  6()].** (overwri
fe50: 74 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75  ting the previou
fe60: 73 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20  s values). Note 
fe70: 74 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  that calls to [s
fe80: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
fe90: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ],.** [sqlite3_e
fea0: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
feb0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
fec0: 29 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  )] themselves do
fed0: 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a   not affect the.
fee0: 2a 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75  ** results of fu
fef0: 74 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  ture invocations
ff00: 2e 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20  .  Calls to API 
ff10: 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f  routines that do
ff20: 20 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61   not return.** a
ff30: 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78  n error code (ex
ff40: 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f  ample: [sqlite3_
ff50: 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64  data_count()]) d
ff60: 6f 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20  o not.** change 
ff70: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72  the error code r
ff80: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
ff90: 72 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66  routine.  Interf
ffa0: 61 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  aces that are.**
ffb0: 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
ffc0: 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20  with a specific 
ffd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ffe0: 69 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  ion (examples:.*
fff0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  * [sqlite3_mprin
10000 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
10010 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
10020 63 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20  cache()] do not 
10030 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
10040 74 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a  turn code.  .**.
10050 2a 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f  ** Assuming no o
10060 74 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67  ther intervening
10070 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
10080 61 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74  alls are made, t
10090 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
100a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
100b0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73  s function is as
100c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
100d0 65 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a  e same error as.
100e0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72  ** the strings r
100f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
10100 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
10110 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
10120 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
10130 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
10140 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
10150 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
10160 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
10170 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
10180 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
10190 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
101a0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
101b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
101c0 0a 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20  .**.** Instance 
101d0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
101e0 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20  epresent single 
101f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
10200 20 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69   This.** is vari
10210 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
10220 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
10230 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22  ment" or a .** "
10240 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
10250 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
10260 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
10270 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c  t"..** .** The l
10280 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
10290 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
102a0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
102b0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
102c0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
102d0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
102e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
102f0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
10300 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
10310 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
10320 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
10330 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e   parameters usin
10340 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
10350 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
10360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e  qlite3_bind_* in
10370 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c  terfaces]..** <l
10380 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
10390 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
103a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
103b0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
103c0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
103d0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
103e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
103f0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
10400 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
10410 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
10420 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
10430 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
10440 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
10450 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
10460 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
10470 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
10480 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
10490 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
104a0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
104b0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
104c0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
104d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
104e0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
104f0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
10500 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
10510 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
10520 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
10530 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
10540 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
10550 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
10560 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
10570 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
10580 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10590 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  . .**.** The fir
105a0 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22  st argument "db"
105b0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20   is an [sqlite3 
105c0 7c 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  | SQLite databas
105d0 65 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62  e handle] .** ob
105e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
105f0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
10600 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
10610 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
10620 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
10630 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54  _open16()]..** T
10640 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10650 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65  nt "zSql" is the
10660 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
10670 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
10680 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
10690 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
106a0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
106b0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
106c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
106d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
106e0 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71  ses UTF-8 and sq
106f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
10700 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
10710 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
10720 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
10730 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  * If the nByte a
10740 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a  rgument is less.
10750 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ** than zero, th
10760 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
10770 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
10780 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
10790 20 20 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73    If.** nByte is
107a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
107b0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
107c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
107d0 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66  .** bytes read f
107e0 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
107f0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
10800 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
10810 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
10820 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
10830 73 74 20 27 5c 30 30 30 27 20 63 68 61 72 61 63  st '\000' charac
10840 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c  ter or .** until
10850 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
10860 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
10870 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
10880 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
10890 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
108a0 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
108b0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
108c0 66 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61  first.** SQL sta
108d0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
108e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   This routine on
108f0 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20  ly compiles the 
10900 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a  first statement.
10910 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  ** in zSql, so *
10920 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
10930 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
10940 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
10950 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
10960 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
10970 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
10980 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
10990 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  mt | SQL stateme
109a0 6e 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68  nt structure] th
109b0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
109c0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
109d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f  ite3_step()].  O
109e0 72 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  r if there is an
109f0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
10a00 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f  may be.** set to
10a10 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
10a20 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
10a30 6e 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ned no SQL (if t
10a40 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a  he input is and.
10a50 2a 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  ** empty string 
10a60 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
10a70 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
10a80 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20  t to NULL.  The 
10a90 63 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65  calling.** proce
10aa0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
10ab0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
10ac0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51   the compiled SQ
10ad0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75  L statement.** u
10ae0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
10af0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
10b00 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
10b10 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f  with it..**.** O
10b20 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
10b30 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
10b40 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
10b50 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
10b60 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65  ROR | error code
10b70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
10b80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10b90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
10ba0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
10bb0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
10bc0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
10bd0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
10be0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
10bf0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
10c00 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
10c10 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
10c20 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
10c30 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
10c40 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
10c50 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
10c60 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
10c70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10c80 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
10c90 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
10ca0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
10cb0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
10cc0 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72  py of the .** or
10cd0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
10ce0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
10cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10d00 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
10d10 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
10d20 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
10d30 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
10d40 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
10d50 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
10d60 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
10d70 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
10d80 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
10d90 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
10da0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
10db0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
10dc0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
10dd0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
10de0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
10df0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
10e00 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
10e10 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
10e20 64 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68  d in a way.** th
10e30 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
10e40 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
10e50 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
10e60 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
10e70 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
10e80 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
10e90 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
10ea0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
10eb0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
10ec0 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
10ed0 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
10ee0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
10ef0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
10f00 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
10f10 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
10f20 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
10f30 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
10f40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
10f50 74 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  t of the parsing
10f60 0a 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72  .** error that r
10f70 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
10f80 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
10f90 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
10fa0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
10fb0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
10fc0 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  , .** [sqlite3_s
10fd0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
10fe0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
10ff0 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49  tailed .** [SQLI
11000 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
11010 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
11020 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
11030 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
11040 75 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20  ult codes] such 
11050 61 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20  as directly..** 
11060 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
11070 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71  ior was that [sq
11080 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
11090 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
110a0 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51  a generic.** [SQ
110b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
110c0 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20  lt code and you 
110d0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
110e0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
110f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11100 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
11110 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
11120 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
11130 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a  f the problem..*
11140 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
11150 70 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63  prepare interfac
11160 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
11170 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
11180 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65  e error is.** re
11190 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
111a0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
111b0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
111c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
111d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
111e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
111f0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
11200 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
11210 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
11220 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
11230 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
11240 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
11250 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
11260 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
11270 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
11280 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
11290 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
112a0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
112b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
112c0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
112d0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
112e0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
112f0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
11300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11310 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
11320 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
11330 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
11340 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
11350 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
11360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
11370 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
11380 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
11390 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
113a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
113b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
113c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
113d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
113e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
113f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
11400 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
11410 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
11420 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
11430 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
11440 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
11450 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
11460 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
11470 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
11480 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
11490 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
114a0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
114b0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
114c0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
114d0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
114e0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
114f0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
11500 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
11510 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
11520 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
11530 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
11540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
11550 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
11560 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
11570 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
11580 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
11590 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
115a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
115b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
115c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
115d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
115e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
115f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
11600 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
11610 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
11620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
11630 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
11640 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
11650 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
11660 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
11670 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
11680 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
11690 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
116a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
116b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
116c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
116d0 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 72 69 65 76 65  ../*.** Retrieve
116e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
116f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 73 6f  L statement asso
11700 63 69 61 74 65 64 20 77 69 74 68 20 61 20 63 6f  ciated with a co
11710 6d 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e 74  mpiled statement
11720 0a 2a 2a 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  .** in UTF-8 enc
11730 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  oding..**.** If 
11740 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  the compiled SQL
11750 20 73 74 61 74 65 6d 65 6e 74 20 70 61 73 73 65   statement passe
11760 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e 74  d as an argument
11770 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
11780 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 73 71  ing.** either sq
11790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
117a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 70 72 65 70   or sqlite3_prep
117b0 61 72 65 31 36 5f 76 32 2c 20 74 68 65 6e 20 74  are16_v2, then t
117c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
117d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
117e0 72 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69  r to a nul-termi
117f0 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
11800 74 61 69 6e 69 6e 67 20 61 20 63 6f 70 79 20 6f  taining a copy o
11810 66 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  f.** the origina
11820 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  l SQL statement.
11830 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 73 20   The pointer is 
11840 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
11850 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 73 20  statement.** is 
11860 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 73 71  deleted using sq
11870 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
11880 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
11890 74 61 74 65 6d 65 6e 74 20 77 61 73 20 63 6f 6d  tatement was com
118a0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
118b0 65 72 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  er of the legacy
118c0 20 69 6e 74 65 72 66 61 63 65 73 20 0a 2a 2a 20   interfaces .** 
118d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
118e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 70 72 65  ) or sqlite3_pre
118f0 70 61 72 65 31 36 28 29 2c 20 74 68 69 73 20 66  pare16(), this f
11900 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11910 4e 55 4c 4c 2e 0a 2a 2a 20 0a 2a 2a 2a 2a 2a 2a  NULL..** .******
11920 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
11930 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
11940 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
11950 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
11960 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
11970 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
11980 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
11990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
119a0 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  :  Dynamically T
119b0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
119c0 74 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  t.**.** SQLite u
119d0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
119e0 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
119f0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61  s it stores.  Va
11a00 6c 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20  lues can .** be 
11a10 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
11a20 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
11a30 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
11a40 20 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a   or NULL.  When.
11a50 2a 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e  ** passing aroun
11a60 64 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61  d values interna
11a70 6c 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20  lly, each value 
11a80 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
11a90 73 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  s.** an instance
11aa0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
11ab0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f  value object..*/
11ac0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
11ad0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
11ae0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
11af0 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f  EF:  SQL Functio
11b00 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
11b10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
11b20 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
11b30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
11b40 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
11b50 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
11b60 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
11b70 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75   A pointer to su
11b80 63 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20  ch an object is 
11b90 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72  the.** first par
11ba0 61 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64  ameter to user-d
11bb0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
11bc0 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ions..*/.typedef
11bd0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
11be0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
11bf0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
11c00 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
11c10 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
11c20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
11c30 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51  .**.** In the SQ
11c40 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20  L strings input 
11c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
11c60 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
11c70 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f  s variants,.** o
11c80 6e 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72  ne or more liter
11c90 61 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61  als can be repla
11ca0 63 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ce by a paramete
11cb0 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  r in one of thes
11cc0 65 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a  e.** forms:.**.*
11cd0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
11ce0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
11cf0 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a  ** <li>  :AAA.**
11d00 20 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c   <li>  @AAA.** <
11d10 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
11d20 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
11d30 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20  parameter forms 
11d40 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20  shown above NNN 
11d50 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  is an integer li
11d60 74 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73  teral,.** AAA is
11d70 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
11d80 20 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20   identifier and 
11d90 56 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c  VVV is a variabl
11da0 65 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67  e name according
11db0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61  .** to the synta
11dc0 78 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54  x rules of the T
11dd0 43 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c  CL programming l
11de0 61 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20  anguage..** The 
11df0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
11e00 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
11e10 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
11e20 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a  rameter names").
11e30 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
11e40 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
11e50 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
11e60 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
11e70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
11e80 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
11e90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
11ea0 20 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73   routines always
11eb0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
11ec0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11ed0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
11ee0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
11ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
11f00 29 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72  )] or.** its var
11f10 69 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f  iants.  The seco
11f20 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  nd.** argument i
11f30 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
11f40 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
11f50 62 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72  be set.  The fir
11f60 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
11f70 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  .** an index of 
11f80 31 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65  1. When the same
11f90 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
11fa0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
11fb0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a  an once, second.
11fc0 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  ** and subsequen
11fd0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
11fe0 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
11ff0 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
12000 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54  t occurrence.  T
12010 68 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20  he index for.** 
12020 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
12030 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
12040 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
12050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
12060 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41  ameter_name()] A
12070 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
12080 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f  The index for "?
12090 4e 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65  NNN".** paramete
120a0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
120b0 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
120c0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
120d0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
120e0 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  e compile-time.*
120f0 2a 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49  * parameter SQLI
12100 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
12110 4e 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20  NUMBER (default 
12120 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20  value: 999)..** 
12130 53 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d  See <a href="lim
12140 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73  its.html">limits
12150 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64  .html</a> for ad
12160 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
12170 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
12180 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
12190 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
121a0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
121b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
121c0 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  hose.** routines
121d0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
121e0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
121f0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e  s value is the n
12200 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
12210 2a 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * in the paramet
12220 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
12230 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
12240 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
12250 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72  es in the.** str
12260 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
12270 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
12280 73 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a  s.  The number.*
12290 2a 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20  * of bytes does 
122a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
122b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
122c0 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74  at the end of st
122d0 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65  rings..** If the
122e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
122f0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
12300 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
12310 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75   string is.** nu
12320 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
12330 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
12340 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
12350 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
12360 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
12370 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
12380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
12390 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
123a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
123b0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
123c0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
123d0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
123e0 0a 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53  .** text after S
123f0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
12400 65 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20  ed with it.  If 
12410 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
12420 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65  nt is the.** spe
12430 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
12440 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
12450 20 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73   the library ass
12460 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e  umes that the in
12470 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  formation.** is 
12480 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
12490 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
124a0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
124b0 62 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68  be freed.  If th
124c0 65 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d  e.** fifth argum
124d0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
124e0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
124f0 45 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  ENT], then SQLit
12500 65 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f  e makes its.** o
12510 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12520 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
12530 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
12540 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
12550 5f 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  _*().** routine 
12560 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
12570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
12580 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
12590 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
125a0 6f 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74  of length n that
125b0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
125c0 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72  th zeros.  A zer
125d0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
125e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
125f0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
12600 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
12610 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  it size) while i
12620 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
12630 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
12640 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
12650 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
12660 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  e-holders for BL
12670 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
12680 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
12690 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20  itten using .** 
126a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
126b0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42  en | increment B
126c0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
126d0 73 2e 20 20 41 20 6e 65 67 61 74 69 76 65 0a 2a  s.  A negative.*
126e0 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  * value for the 
126f0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
12700 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
12710 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68  h BLOB..**.** Th
12720 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
12730 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  () routines must
12740 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72   be called after
12750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
12760 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20  pare_v2()] (and 
12770 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72  its variants) or
12780 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
12790 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65  )] and.** before
127a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
127b0 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  ]..** Bindings a
127c0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
127d0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
127e0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
127f0 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61  .** Unbound para
12800 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
12810 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
12820 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12830 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
12840 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
12850 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63  ss or an error c
12860 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69  ode if.** anythi
12870 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20  ng goes wrong.  
12880 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
12890 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
128a0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
128b0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
128c0 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e  ange.  [SQLITE_N
128d0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
128e0 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c  d if malloc fail
128f0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
12900 53 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65  SUSE] is returne
12910 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
12920 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
12930 6e 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  n a virtual.** m
12940 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
12950 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
12960 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
12970 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
12980 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
12990 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
129a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
129b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
129c0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
129d0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
129e0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
129f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
12a00 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
12a10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
12a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12a30 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
12a40 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
12a50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12a60 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
12a70 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
12a80 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
12a90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
12aa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12ab0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
12ac0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
12ad0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
12ae0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
12af0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12b00 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
12b10 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
12b20 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
12b30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
12b40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
12b50 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
12b60 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
12b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
12b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12b90 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
12ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
12bb0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
12bc0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
12bd0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73   Host Parameters
12be0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
12bf0 65 20 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70  e largest host p
12c00 61 72 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69  arameter index i
12c10 6e 20 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65  n the precompile
12c20 64 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65  d statement give
12c30 6e 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75  n.** as the argu
12c40 6d 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20  ment.  When the 
12c50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
12c60 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  are of the forms
12c70 20 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20   like ":AAA".** 
12c80 6f 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65  or "?", then the
12c90 79 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73  y are assigned s
12ca0 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61  equential increa
12cb0 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67  sing numbers beg
12cc0 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f  inning.** with o
12cd0 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65  ne, so the value
12ce0 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
12cf0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
12d00 65 74 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a  eters.  However.
12d10 2a 2a 20 69 66 20 74 68 65 20 73 61 6d 65 20 68  ** if the same h
12d20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
12d30 6d 65 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69  me is used multi
12d40 70 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20  ple times, each 
12d50 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73  occurrance.** is
12d60 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
12d70 6e 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76  number, so the v
12d80 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e  alue returned in
12d90 20 74 68 61 74 20 63 61 73 65 20 69 73 20 74 68   that case is th
12da0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75  e number.** of u
12db0 6e 69 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d  nique host param
12dc0 65 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20  eter names.  If 
12dd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
12de0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
12df0 4e 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28  N".** are used (
12e00 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20  where NNN is an 
12e10 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68  integer) then th
12e20 65 72 65 20 6d 69 67 68 74 20 62 65 20 67 61 70  ere might be gap
12e30 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  s in the.** numb
12e40 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61  ering and the va
12e50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12e60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
12e70 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
12e80 68 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d  he.** host param
12e90 65 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61  eter with the la
12ea0 72 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75  rgest index valu
12eb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  e..**.** The pre
12ec0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
12ed0 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c  must not be [sql
12ee0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
12ef0 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72  finalized].** pr
12f00 69 6f 72 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ior to this rout
12f10 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67 2e 20  ine returnning. 
12f20 20 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 72   Otherwise the r
12f30 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
12f40 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62  ined.** and prob
12f50 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
12f60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12f70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
12f80 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
12f90 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
12fa0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
12fb0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
12fc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
12fd0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
12fe0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
12ff0 20 6f 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   of the n-th par
13000 61 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a 2a 20  ameter in a .** 
13010 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13030 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70 61 72  nt]..** Host par
13040 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
13050 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 22 40  orm ":AAA" or "@
13060 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 20 68  AAA" or "$VVV" h
13070 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68  ave a name.** wh
13080 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
13090 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  g ":AAA" or "@AA
130a0 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20 20 0a  A" or "$VVV".  .
130b0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
130c0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
130d0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
130e0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
130f0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
13100 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
13110 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
13120 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76  ?" or "?NNN" hav
13130 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  e no name..**.**
13140 20 54 68 65 20 66 69 72 73 74 20 62 6f 75 6e 64   The first bound
13150 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
13160 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
13170 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
13180 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
13190 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
131a0 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
131b0 65 72 20 69 73 20 6e 61 6d 65 6c 65 73 73 2c 0a  er is nameless,.
131c0 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  ** then NULL is 
131d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
131e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
131f0 73 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 0a  s always in the.
13200 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  ** UTF-8 encodin
13210 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
13220 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
13230 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  s originally spe
13240 63 69 66 69 65 64 0a 2a 2a 20 61 73 20 55 54 46  cified.** as UTF
13250 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
13260 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 20  prepare16()] or 
13270 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13280 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
13290 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
132a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
132b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
132c0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
132d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
132e0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
132f0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
13300 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
13310 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
13320 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f 73 74   index of a host
13330 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
13340 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 2e 0a  the given name..
13350 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  ** The name must
13360 20 6d 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20   match exactly. 
13370 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 74 65 72   If no parameter
13380 20 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20   with the given 
13390 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f 75 6e  name is .** foun
133a0 64 2c 20 72 65 74 75 72 6e 20 30 2e 20 20 50 61  d, return 0.  Pa
133b0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75  rameter names mu
133c0 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69  st be UTF8..*/.i
133d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
133e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
133f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
13400 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
13410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13420 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
13430 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
13440 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
13450 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
13460 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
13470 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
13480 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
13490 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20  ot.** reset the 
134a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
134b0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
134c0 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  n a .** [sqlite3
134d0 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
134e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
134f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
13500 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
13510 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
13520 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
13530 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
13540 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
13550 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
13560 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
13570 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
13580 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52  sult Set.**.** R
13590 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
135a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
135b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
135c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a  turned by the .*
135d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
135e0 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  | compiled SQL s
135f0 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
13600 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
13610 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73  0.** if pStmt is
13620 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
13630 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
13640 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
13650 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20   .** example an 
13660 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20  UPDATE)..*/.int 
13670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
13680 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
13690 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
136a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
136b0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
136c0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54  sult Set.**.** T
136d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
136e0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
136f0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
13700 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
13710 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
13720 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  et of a SELECT s
13730 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73  tatement.  The s
13740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
13750 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
13760 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
13770 74 65 72 20 74 6f 20 61 20 55 54 46 38 20 73 74  ter to a UTF8 st
13780 72 69 6e 67 20 61 6e 64 20 73 71 6c 69 74 65 33  ring and sqlite3
13790 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
137a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
137b0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 31 36  inter to a UTF16
137c0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
137d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
137e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
137f0 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
13800 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13810 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
13820 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
13830 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
13840 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
13850 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
13860 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
13870 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
13880 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
13890 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
138a0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
138b0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
138c0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  e .** [sqlite3_s
138d0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
138e0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
138f0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
13900 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
13910 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
13920 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ext call sqlite3
13930 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
13940 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
13950 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20  _name16().** on 
13960 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
13970 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
13980 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
13990 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
139a0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
139b0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
139c0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
139d0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
139e0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
139f0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
13a00 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
13a10 75 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  urned..*/.const 
13a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
13a30 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
13a40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
13a50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
13a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
13a70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
13a80 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
13a90 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
13aa0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
13ab0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
13ac0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
13ad0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
13ae0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68   to determine wh
13af0 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61  at column of wha
13b00 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68  t.** table in wh
13b10 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72  ich database a r
13b20 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43  esult of a SELEC
13b30 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  T statement come
13b40 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
13b50 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
13b60 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
13b70 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
13b80 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
13b90 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54  her a UTF8 or UT
13ba0 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  F16 string.  The
13bb0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
13bc0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
13bd0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
13be0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
13bf0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
13c00 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
13c10 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
13c20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
13c30 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
13c40 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
13c50 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
13c60 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b  d until.** the [
13c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
13c80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13c90 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  t] is destroyed 
13ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
13cb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
13cc0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
13cd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
13ce0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
13cf0 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
13d00 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
13d10 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
13d20 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
13d30 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
13d40 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
13d50 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
13d60 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
13d70 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13d80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
13d90 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
13da0 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
13db0 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
13dc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  QL statement]..*
13dd0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
13de0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
13df0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
13e00 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
13e10 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74  ed by .** the st
13e20 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
13e30 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
13e40 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
13e50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
13e60 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
13e70 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
13e80 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
13e90 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75  sion.** or subqu
13ea0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
13eb0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
13ec0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
13ed0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
13ee0 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72  turn NULL. Other
13ef0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
13f00 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f  n the .** name o
13f10 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
13f20 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
13f30 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
13f40 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63  uery result.** c
13f50 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
13f60 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
13f70 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
13f80 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
13f90 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77  hose postfixed w
13fa0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 20  ith "16" return 
13fb0 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65  UTF-16.** encode
13fc0 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f  d strings, the o
13fd0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
13fe0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
13ff0 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
14000 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
14010 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
14020 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
14030 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
14040 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
14050 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
14060 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
14070 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
14080 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
14090 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
140a0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
140b0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
140c0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
140d0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
140e0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
140f0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
14100 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
14110 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
14120 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
14130 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
14140 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
14150 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
14160 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
14170 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
14180 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
14190 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
141a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
141b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
141c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
141d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
141e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
141f0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
14200 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
14210 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
14220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
14230 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
14240 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
14250 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
14260 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
14270 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
14280 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
14290 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
142a0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
142b0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
142c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
142d0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c  ameter is a [sql
142e0 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
142f0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
14300 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73  nt]. .** If this
14310 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
14320 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
14330 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
14340 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72  umn of the .** r
14350 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
14360 65 74 20 20 6f 66 20 74 68 61 74 20 53 45 4c 45  et  of that SELE
14370 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  CT is a table co
14380 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
14390 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
143a0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
143b0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
143c0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
143d0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
143e0 64 2e 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  d. If the Nth co
143f0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
14400 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
14410 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
14420 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
14430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
14440 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
14450 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
14460 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
14470 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61  encoded. For exa
14480 6d 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20  mple, in.** the 
14490 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
144a0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
144b0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
144c0 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68  T);.**.** And th
144d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
144e0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a  ement compiled:.
144f0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
14500 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
14510 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73  .**.** Then this
14520 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
14530 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
14540 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
14550 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73  he second.** res
14560 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  ult column (i==1
14570 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
14580 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
14590 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
145a0 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  n.** (i==0)..**.
145b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
145c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
145d0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
145e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
145f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
14600 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
14610 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
14620 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
14630 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
14640 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
14650 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
14660 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
14670 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
14680 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
14690 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
146a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
146b0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
146c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
146d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
146e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
146f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
14700 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
14710 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
14720 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
14730 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
14740 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20  te3_stmt *, int 
14750 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  i);.const void *
14760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
14770 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
14780 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
14790 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  * .** CAPI3REF: 
147a0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
147b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
147c0 20 41 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74   After an [sqlit
147d0 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74  e3_stmt | SQL st
147e0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
147f0 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20  n prepared with 
14800 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74  a call.** to eit
14810 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
14820 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
14830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
14840 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65  _v2()] or to one
14850 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63   of.** the legac
14860 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
14870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
14880 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
14890 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68  pare16()],.** th
148a0 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  en this function
148b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
148c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
148d0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
148e0 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  e .** statement.
148f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
14900 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
14910 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74  or of this sqlit
14920 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
14930 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
14940 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
14950 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
14960 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
14970 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
14980 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
14990 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
149a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
149b0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
149c0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
149d0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
149e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
149f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
14a00 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
14a10 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
14a20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
14a30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
14a40 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
14a50 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
14a60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
14a70 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
14a80 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
14a90 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61  *.** In the laga
14aa0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
14ab0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
14ac0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
14ad0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a  QLITE_BUSY], .**
14ae0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
14af0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
14b00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
14b10 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
14b20 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
14b30 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
14b40 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
14b50 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
14b60 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b  lt code].** or [
14b70 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
14b80 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
14b90 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20  ult code] might 
14ba0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
14bb0 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  * well..**.** [S
14bc0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
14bd0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
14be0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
14bf0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
14c00 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14c10 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
14c20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
14c30 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
14c40 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20   is a COMMIT.** 
14c50 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
14c60 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
14c70 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
14c80 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
14c90 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
14ca0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
14cb0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f  ment is not a CO
14cc0 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20  MMIT and occurs 
14cd0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
14ce0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
14cf0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
14d00 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
14d10 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
14d20 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
14d30 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
14d40 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
14d50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
14d60 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
14d70 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
14d80 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
14d90 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
14da0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
14db0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
14dc0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
14dd0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
14de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
14df0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
14e00 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
14e10 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
14e20 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
14e30 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
14e40 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
14e50 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
14e60 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a  any data, then .
14e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ** [SQLITE_ROW] 
14e80 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
14e90 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
14ea0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
14eb0 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69  .** for processi
14ec0 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ng by the caller
14ed0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
14ee0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
14ef0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
14f00 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
14f10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
14f20 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
14f30 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
14f40 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
14f50 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
14f60 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
14f70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
14f80 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
14f90 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
14fa0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
14fb0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
14fc0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
14fd0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
14fe0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
14ff0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
15000 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
15010 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
15020 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
15030 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
15040 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
15050 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
15060 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
15070 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
15080 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53   (example:.** [S
15090 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
150a0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
150b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
150c0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
150d0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
150e0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
150f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15100 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71  )] on the.** [sq
15110 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
15120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
15130 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
15140 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
15150 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
15160 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
15170 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
15180 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
15190 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
151a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
151b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
151c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
151d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
151e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
151f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73  s called on a [s
15200 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
15210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15220 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
15230 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
15240 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
15250 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
15260 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a  one that had .**
15270 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
15280 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
15290 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
152a0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
152b0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
152c0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
152d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
152e0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
152f0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
15300 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
15310 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
15320 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n time..**.** <b
15330 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
15340 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49   Alert:</b>.** I
15350 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
15360 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20  erface, .** the 
15370 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41  sqlite3_step() A
15380 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
15390 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
153a0 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49  r code,.** [SQLI
153b0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
153c0 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f  wing any error o
153d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
153e0 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b  E_BUSY].** and [
153f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
15400 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b   You must call [
15410 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
15420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
15430 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
15440 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
15450 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63   of the specific
15460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
15470 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
15480 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
15490 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
154a0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
154b0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
154c0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
154d0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
154e0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
154f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
15500 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
15510 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
15520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15530 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
15540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15550 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
15560 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
15570 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
15580 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
15590 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
155a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
155b0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
155c0 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63  he .** more spec
155d0 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  ific [SQLITE_ERR
155e0 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
155f0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
15600 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
15610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
15620 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
15630 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
15640 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
15650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
15660 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
15670 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15680 46 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  F:.**.** Return 
15690 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
156a0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
156b0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
156c0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
156d0 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
156e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
156f0 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b  ] that returns [
15700 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 69  SQLITE_ROW], thi
15710 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c  s routine.** wil
15720 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
15730 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 20 5b  e value as the [
15740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
15750 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e  ount()] function
15760 2e 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71 6c 69  ..** After [sqli
15770 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
15780 72 65 74 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c  returned an [SQL
15790 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
157a0 54 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20  TE_BUSY], or.** 
157b0 61 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  a [SQLITE_ERROR 
157c0 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f  | error code], o
157d0 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
157e0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
157f0 65 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  en .** called on
15800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
15810 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
15820 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65  atement] for the
15830 20 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20   first time,.** 
15840 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
15850 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
15860 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
15870 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
15880 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
15890 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
158a0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
158b0 73 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 76 61  s.**.** Every va
158c0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
158d0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
158e0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
158f0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
15900 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
15910 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
15920 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
15930 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
15940 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
15950 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
15960 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
15970 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
15980 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
15990 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
159a0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
159b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
159c0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
159d0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
159e0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
159f0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
15a00 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
15a10 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
15a20 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
15a30 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
15a40 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
15a50 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
15a60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
15a70 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
15a80 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53  E3_TEXT not.** S
15a90 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
15aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
15ab0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
15ac0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
15ad0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
15ae0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
15af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
15b00 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
15b10 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
15b20 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
15b30 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
15b40 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
15b50 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
15b60 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
15b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15b80 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73  : Results Values
15b90 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
15ba0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15bb0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
15bc0 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61  ation about.** a
15bd0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
15be0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  f the current re
15bf0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
15c00 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a  ery.  In every.*
15c10 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  * case the first
15c20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
15c30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ointer to the .*
15c40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
15c50 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d  | SQL statement]
15c60 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a   that is being.*
15c70 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  * evaluated (the
15c80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
15c90 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
15ca0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
15cb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
15cc0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
15cd0 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a   variants) and.*
15ce0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * the second arg
15cf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
15d00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
15d10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
15d20 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c  mation .** shoul
15d30 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
15d40 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
15d50 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
15d60 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e  lt set.** has an
15d70 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a   index of 0..**.
15d80 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
15d90 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63  atement is not c
15da0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
15db0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
15dc0 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20  r if the.** the 
15dd0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
15de0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
15df0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
15e00 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65  fined. .** These
15e10 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
15e20 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
15e30 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
15e40 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
15e50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
15e60 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
15e70 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
15e80 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
15e90 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
15ea0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
15eb0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20  ] has been call 
15ec0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
15ed0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
15ee0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
15ef0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
15f00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
15f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
15f20 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
15f30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15f40 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
15f50 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
15f60 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
15f70 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
15f80 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
15f90 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
15fa0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
15fb0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
15fc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
15fd0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
15fe0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
15ff0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
16000 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
16010 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
16020 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
16030 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
16040 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ined.  .**.** Th
16050 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
16060 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
16070 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
16080 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
16090 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
160a0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
160b0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
160c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
160d0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61   The returned va
160e0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
160f0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
16100 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
16110 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
16120 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
16130 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
16140 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
16150 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
16160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
16170 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
16180 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
16190 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
161a0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
161b0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
161c0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
161d0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
161e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
161f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
16200 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
16210 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
16220 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
16230 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
16240 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
16250 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
16260 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
16270 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
16280 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
16290 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
162a0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
162b0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
162c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
162d0 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e  tes() .** routin
162e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
162f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
16300 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
16310 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
16320 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
16330 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
16340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16350 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
16360 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
16370 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
16380 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16390 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
163a0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
163b0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
163c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
163d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
163e0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
163f0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
16400 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
16410 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
16420 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
16430 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
16440 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
16450 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
16460 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
16470 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
16480 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
16490 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
164a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
164b0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
164c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
164d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
164e0 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
164f0 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
16500 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
16510 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e  ers..**.** Strin
16520 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
16530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16540 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
16550 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
16560 2c 0a 2a 2a 20 65 76 65 6e 20 7a 65 72 6f 2d 6c  ,.** even zero-l
16570 65 6e 67 74 68 20 73 74 72 69 6e 67 73 2c 20 61  ength strings, a
16580 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
16590 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
165a0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
165b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
165c0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
165d0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
165e0 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  b is an arbitrar
165f0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
16600 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
16610 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
16620 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
16630 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
16640 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
16650 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
16660 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
16670 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
16680 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
16690 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
166a0 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74    .** The zero t
166b0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
166c0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
166d0 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
166e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
166f0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
16700 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
16710 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
16720 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
16730 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
16740 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
16750 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
16760 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
16770 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
16780 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
16790 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
167a0 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76  y to do the conv
167b0 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61  ersion.** automa
167c0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
167d0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
167e0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
167f0 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72  sions that.** ar
16800 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
16810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
16820 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
16830 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
16840 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
16850 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
16860 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
16870 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
16880 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
16890 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
168a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
168b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
168c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
168d0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
168e0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
168f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
16900 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
16910 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
16920 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
16930 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
16940 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
16950 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
16960 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
16970 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
16980 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
16990 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
169a0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
169b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
169c0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
169d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
169e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
169f0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
16a00 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
16a10 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
16a20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45  Same as for INTE
16a30 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
16a40 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
16a50 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
16a60 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
16a70 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
16a80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
16a90 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
16aa0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
16ab0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
16ac0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
16ad0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
16ae0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
16af0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
16b00 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
16b10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
16b20 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
16b30 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
16b40 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
16b50 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
16b60 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
16b70 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
16b80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
16b90 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
16ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
16bb0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
16bc0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
16bd0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
16be0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
16bf0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
16c00 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
16c10 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
16c20 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
16c30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
16c40 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
16c50 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
16c60 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
16c70 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
16c80 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
16c90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
16ca0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
16cb0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
16cc0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
16cd0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
16ce0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
16cf0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
16d00 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
16d10 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
16d20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
16d30 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74  n equavalent int
16d40 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
16d50 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
16d60 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
16d70 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
16d80 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
16d90 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
16da0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
16db0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
16dc0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
16dd0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
16de0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
16df0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
16e00 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
16e10 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
16e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
16e30 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
16e40 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
16e50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
16e60 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
16e70 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
16e80 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  . .** Type conve
16e90 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
16ea0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
16eb0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
16ec0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
16ed0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
16ee0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  l>.** <li><p>  T
16ef0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
16f00 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
16f10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16f20 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20  text() .**      
16f30 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63      or sqlite3_c
16f40 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
16f50 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
16f60 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
16f70 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ht.**          n
16f80 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
16f90 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
16fa0 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
16fb0 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
16fc0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
16fd0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
16fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
16ff0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
17000 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
17010 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
17020 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
17030 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
17040 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
17050 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70     to UTF-16.</p
17060 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
17070 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
17080 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
17090 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
170a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
170b0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  s() or.**       
170c0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
170d0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
170e0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
170f0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
17100 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
17110 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69  o UTF-8.</p></li
17120 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
17130 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74   Conversions bet
17140 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
17150 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
17160 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
17170 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
17180 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
17190 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
171a0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
171b0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
171c0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
171d0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
171e0 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c  er points to wil
171f0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
17200 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
17210 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
17220 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
17230 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
17240 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
17250 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a  ometime it is.**
17260 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
17270 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
17280 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
17290 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
172a0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66    .**.** The saf
172b0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
172c0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
172d0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
172e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
172f0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
17300 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
17310 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20  **.**  <ul>.**  
17320 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
17330 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
17340 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
17350 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
17360 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
17370 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
17380 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
17390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
173a0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
173b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
173c0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
173d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
173e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
173f0 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  >.**  </ul>.**.*
17400 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
17410 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
17420 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
17430 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
17440 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a  _column_blob(),.
17450 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ** or sqlite3_co
17460 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
17470 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
17480 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65   result into the
17490 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d   desired.** form
174a0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
174b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
174c0 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65  ytes() or sqlite
174d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
174e0 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68  () to.** find th
174f0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
17500 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
17510 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  x call to sqlite
17520 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
17530 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
17540 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
17550 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
17560 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
17570 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a  ().  And do not.
17580 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ** mix calls to 
17590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
175a0 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c  ext16() with cal
175b0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
175c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
175d0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
175e0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
175f0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
17600 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
17610 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
17620 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
17630 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
17640 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17650 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
17660 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
17670 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
17680 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
17690 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
176a0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f  rings.** and blo
176b0 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  bs is freed auto
176c0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
176d0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
176e0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
176f0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
17700 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
17710 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
17720 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
17730 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  nto .** [sqlite3
17740 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
17750 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
17760 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
17770 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
17780 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
17790 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
177a0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
177b0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
177c0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
177d0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
177e0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
177f0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
17800 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
17810 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
17820 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
17830 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
17840 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
17850 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
17860 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
17870 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
17880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
17890 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
178a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
178b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
178c0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
178d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
178e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
178f0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
17900 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
17910 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
17920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
17930 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
17940 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
17950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
17960 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
17970 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
17980 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17990 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
179a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
179b0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
179c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
179d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
179e0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
179f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
17a00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
17a10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
17a20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
17a30 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
17a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
17a50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
17a60 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
17a70 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
17a80 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
17a90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
17aa0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
17ab0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
17ac0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
17ad0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
17ae0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17af0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
17b00 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
17b10 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 73   delete a .** [s
17b20 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f  qlite3_stmt | co
17b30 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
17b40 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74  ment]. If the st
17b50 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65  atement was.** e
17b60 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
17b70 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65  ully, or not exe
17b80 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
17b90 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  en SQLITE_OK is 
17ba0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
17bb0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
17bc0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
17bd0 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 53  d then an .** [S
17be0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72  QLITE_ERROR | er
17bf0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51  ror code] or [SQ
17c00 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
17c10 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72  | extended error
17c20 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74   code].** is ret
17c30 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  urned. .**.** Th
17c40 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
17c50 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
17c60 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
17c70 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
17c80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  e.** [sqlite3_st
17c90 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 6d 61 63  mt | virtual mac
17ca0 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 65 20 76  hine].  If the v
17cb0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
17cc0 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c  as not .** compl
17cd0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
17ce0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
17cf0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
17d00 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
17d10 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
17d20 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70  r or an interrup
17d30 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65  t.  (See [sqlite
17d40 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29  3_interrupt()].)
17d50 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20   .** Incomplete 
17d60 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
17d70 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
17d80 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
17d90 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65  elled,  .** depe
17da0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72  nding on the cir
17db0 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20  cumstances, and 
17dc0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
17dd0 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63  ERROR | result c
17de0 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69  ode] returned wi
17df0 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42  ll be [SQLITE_AB
17e00 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ORT]..*/.int sql
17e10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
17e20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
17e30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
17e40 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
17e50 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
17e60 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
17e70 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
17e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
17e90 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a  led to reset a .
17ea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
17eb0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
17ec0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
17ed0 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74  t..** back to it
17ee0 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  's initial state
17ef0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
17f00 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e  -executed..** An
17f10 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
17f20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
17f30 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
17f40 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
17f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
17f60 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
17f70 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
17f80 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
17f90 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
17fa0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
17fb0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
17fc0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f  the bindings..*/
17fd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
17fe0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
17ff0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
18000 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
18010 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
18020 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
18030 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
18040 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  wo functions are
18050 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
18060 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
18070 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74  gregates.** or t
18080 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
18090 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74  ehavior of exist
180a0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
180b0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
180c0 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65    The.** differe
180d0 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e  nce only between
180e0 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74   the two is that
180f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
18100 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61  meter, the.** na
18110 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
18120 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  r) function or a
18130 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
18140 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
18150 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
18160 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
18170 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71  nd UTF-16 for sq
18180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18190 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
181a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
181b0 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71 6c 69  ent is the [sqli
181c0 74 65 33 20 7c 20 64 61 74 61 62 61 73 65 20 68  te3 | database h
181d0 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f 6c 64  andle] that hold
181e0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  s the.** SQL fun
181f0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
18200 74 65 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  te is to be adde
18210 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20  d or redefined. 
18220 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70  If a single.** p
18230 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
18240 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
18250 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e  se handle intern
18260 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a  ally, then SQL.*
18270 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  * functions or a
18280 67 67 72 65 67 61 74 65 73 20 6d 75 73 74 20 62  ggregates must b
18290 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
182a0 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74  ally to each dat
182b0 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20  abase.** handle 
182c0 77 69 74 68 20 77 68 69 63 68 20 74 68 65 79 20  with which they 
182d0 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a  will be used..**
182e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
182f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
18300 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
18310 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
18320 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64  reated.** or red
18330 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c  efined..** The l
18340 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
18350 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
18360 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
18370 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20  sive of the .** 
18380 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
18390 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
183a0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
183b0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
183c0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
183d0 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
183e0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
183f0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
18400 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
18410 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49  esult in an SQLI
18420 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a  TE_ERROR error..
18430 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
18440 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
18450 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
18460 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
18470 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
18480 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
18490 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65  . If this parame
184a0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
184b0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
184c0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
184d0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
184e0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
184f0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
18500 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
18510 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
18520 70 65 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a  pecifies what .*
18530 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
18540 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
18550 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
18560 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
18570 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
18580 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69    Any SQL functi
18590 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
185a0 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65  n should be able
185b0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b   to work.** work
185c0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
185d0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
185e0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
185f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
18600 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
18610 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
18620 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
18630 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c  other.  It is al
18640 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f  lowed to.** invo
18650 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
18660 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
18670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
18680 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
18690 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
186a0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
186b0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
186c0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
186d0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57  f eTextRep..** W
186e0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
186f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
18700 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
18710 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
18720 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
18730 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
18740 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
18750 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
18760 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
18770 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
18780 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
18790 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
187a0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
187b0 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63  what.** text enc
187c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
187d0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
187e0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
187f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59  e.** [SQLITE_ANY
18800 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
18810 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
18820 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
18830 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
18840 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
18850 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  the function can
18860 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
18870 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
18880 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75  ng.** [sqlite3_u
18890 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
188a0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
188b0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
188c0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
188d0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
188e0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
188f0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
18900 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
18910 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
18920 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
18930 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41   or aggregate. A
18940 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
18950 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
18960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18970 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20  of.** the xFunc 
18980 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
18990 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
189a0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
189b0 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e   the xStep.** an
189c0 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74  d xFinal paramet
189d0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
189e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
189f0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
18a00 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
18a10 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
18a20 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
18a30 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
18a40 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
18a50 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53  an.** existing S
18a60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
18a70 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
18a80 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
18a90 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
18aa0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74  llback..**.** It
18ab0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
18ac0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
18ad0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
18ae0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
18af0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
18b00 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
18b10 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
18b20 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
18b30 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
18b40 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65   or differing pe
18b50 72 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  rferred text enc
18b60 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20  odings.  SQLite 
18b70 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
18b80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
18b90 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
18ba0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
18bb0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
18bc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
18bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18be0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
18bf0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20  (.  sqlite3 *,. 
18c00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
18c10 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
18c20 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
18c30 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c  extRep,.  void*,
18c40 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
18c50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
18c60 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
18c70 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
18c80 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
18c90 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
18ca0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
18cb0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
18cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
18cd0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
18ce0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
18cf0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  16(.  sqlite3*,.
18d00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
18d10 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
18d20 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
18d30 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a  TextRep,.  void*
18d40 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
18d50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
18d60 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
18d70 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
18d80 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
18d90 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
18da0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
18db0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
18dc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
18dd0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
18de0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
18df0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
18e00 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
18e10 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
18e20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
18e30 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
18e40 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
18e50 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
18e60 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
18e70 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
18e80 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
18e90 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
18ea0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
18eb0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
18ec0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18ed0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
18ee0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
18ef0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18f00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f10 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
18f20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
18f30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
18f40 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
18f50 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
18f60 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
18f70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
18f80 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
18f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18fa0 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74  : Obsolete Funct
18fb0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
18fc0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
18fd0 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e  ll now obsolete.
18fe0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
18ff0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
19000 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
19010 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
19020 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74  e, we continue t
19030 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65  o support.** the
19040 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48  se functions.  H
19050 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65  owever, new deve
19060 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73  lopment projects
19070 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
19080 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
19090 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
190a0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
190b0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
190c0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
190d0 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
190e0 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
190f0 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79  ll you want they
19100 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69   do..*/.int sqli
19110 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
19120 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
19130 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ext*);.int sqlit
19140 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
19150 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
19160 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
19170 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
19180 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
19190 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
191a0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
191b0 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73  er(void);.void s
191c0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
191d0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74  eanup(void);.int
191e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
191f0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
19200 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
19210 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
19220 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
19230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
19240 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
19250 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
19260 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
19270 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
19280 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
19290 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
192a0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
192b0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
192c0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
192d0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
192e0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
192f0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
19300 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
19310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
19320 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
19330 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
19340 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
19350 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
19360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
19370 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
19380 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
19390 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
193a0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
193b0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
193c0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
193d0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
193e0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
193f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
19400 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
19410 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
19420 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  nters to.** [sql
19430 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
19440 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
19450 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
19460 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
19470 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
19480 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
19490 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
194a0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
194b0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
194c0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
194d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
194e0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
194f0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
19500 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
19510 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b  responding .** [
19520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
19530 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  lob | sqlite3_co
19540 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d  lumn_* routines]
19550 20 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a   except that .**
19560 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
19570 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73  take a single [s
19580 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
19590 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
195a0 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
195b0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
195c0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
195d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
195e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
195f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
19600 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
19610 73 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67  s a UTF16 string
19620 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
19630 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
19640 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
19650 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
19660 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
19670 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
19680 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
19690 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
196a0 74 72 61 63 74 20 55 54 46 31 36 20 73 74 72 69  tract UTF16 stri
196b0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
196c0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
196d0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
196e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
196f0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
19700 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
19710 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
19720 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
19730 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
19740 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
19750 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
19760 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
19770 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
19780 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
19790 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
197a0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
197b0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
197c0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
197d0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
197e0 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a  tion (in order.*
197f0 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 76  * words if the v
19800 61 6c 75 65 20 69 73 20 6f 72 69 67 69 6e 61 6c  alue is original
19810 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
19820 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
19830 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  er).** then it i
19840 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69  s done.  Otherwi
19850 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
19860 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a   occurs.  The .*
19870 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
19880 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
19890 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
198a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
198b0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
198c0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
198d0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
198e0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  at the pointer t
198f0 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  hat.** is return
19900 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
19910 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
19920 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
19930 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
19940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19950 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
19960 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
19970 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
19980 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
19990 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
199a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
199b0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
199c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
199d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
199e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
199f0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72    .**.** These r
19a00 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
19a10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
19a20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
19a30 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
19a40 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
19a50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
19a60 75 65 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  ue* parameters..
19a70 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65 20 73 71  ** Or, if the sq
19a80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 61 72 67  lite3_value* arg
19a90 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ument comes from
19aa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
19ab0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a  lumn_value()].**
19ac0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 6e   interface, then
19ad0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
19ae0 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64  should be called
19af0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
19b00 68 72 65 61 64 0a 2a 2a 20 74 68 61 74 20 72 61  hread.** that ra
19b10 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  n [sqlite3_colum
19b20 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2f 0a 63  n_value()]..*/.c
19b30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
19b40 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
19b50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19b60 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19b70 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
19b80 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
19b90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
19ba0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
19bb0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
19bc0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
19bd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
19bf0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
19c00 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
19c10 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
19c20 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
19c30 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
19c40 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
19c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19c60 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
19c70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
19c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19c90 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
19ca0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
19cb0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
19cc0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
19cd0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
19ce0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
19cf0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
19d00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
19d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
19d20 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
19d30 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
19d40 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
19d50 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
19d60 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
19d70 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
19d80 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
19d90 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68  Context.**.** Th
19da0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
19db0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
19dc0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
19dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
19de0 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74  allocate.** a st
19df0 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72  ructure for stor
19e00 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
19e10 20 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65    The first time
19e20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
19e30 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
19e40 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
19e50 65 67 61 74 65 2c 20 61 20 6e 65 77 20 73 74 72  egate, a new str
19e60 75 63 74 75 72 65 20 6f 66 20 73 69 7a 65 20 6e  ucture of size n
19e70 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 6c 6c 6f  Bytes.** is allo
19e80 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 2c 20 61  cated, zeroed, a
19e90 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 6e  nd returned.  On
19ea0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
19eb0 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a 20 73 61  s (for the.** sa
19ec0 6d 65 20 61 67 67 72 65 67 61 74 65 20 69 6e 73  me aggregate ins
19ed0 74 61 6e 63 65 29 20 74 68 65 20 73 61 6d 65 20  tance) the same 
19ee0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
19ef0 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  ed.  The impleme
19f00 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
19f10 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20  e aggregate can 
19f20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64  use the returned
19f30 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
19f40 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
19f50 2a 20 54 68 65 20 62 75 66 66 65 72 20 61 6c 6c  * The buffer all
19f60 6f 63 61 74 65 64 20 69 73 20 66 72 65 65 64 20  ocated is freed 
19f70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
19f80 20 53 51 4c 69 74 65 20 77 68 61 6e 20 74 68 65   SQLite whan the
19f90 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75   aggregate.** qu
19fa0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
19fb0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
19fc0 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
19fd0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
19fe0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
19ff0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
1a000 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
1a010 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  at is the first.
1a020 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1a030 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  the callback rou
1a040 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
1a050 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
1a060 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
1a070 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1a080 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
1a090 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
1a0a0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
1a0b0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
1a0c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
1a0d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
1a0e0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
1a0f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
1a100 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
1a110 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
1a120 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
1a130 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
1a140 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ions.**.** The p
1a150 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
1a160 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1a170 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1a180 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
1a190 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1a1a0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
1a1b0 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 72  nes.** used to r
1a1c0 65 67 69 73 74 65 72 20 75 73 65 72 20 66 75 6e  egister user fun
1a1d0 63 74 69 6f 6e 73 20 69 73 20 61 76 61 69 6c 61  ctions is availa
1a1e0 62 6c 65 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ble to.** the im
1a1f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1a200 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 69  the function usi
1a210 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2a  ng this call..**
1a220 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1a230 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1a240 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
1a250 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
1a260 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a270 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
1a280 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
1a290 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
1a2a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
1a2b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
1a2c0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
1a2d0 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
1a2e0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
1a2f0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
1a300 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
1a310 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
1a320 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
1a330 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
1a340 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
1a350 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
1a360 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
1a370 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
1a380 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
1a390 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
1a3a0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
1a3b0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
1a3c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
1a3d0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
1a3e0 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70  ta-data may be p
1a3f0 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
1a400 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
1a410 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
1a420 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
1a430 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
1a440 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
1a450 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
1a460 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
1a470 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
1a480 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
1a490 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73  .** meta-data as
1a4a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1a4b0 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
1a4c0 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
1a4d0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
1a4e0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
1a4f0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
1a500 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
1a510 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
1a520 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
1a530 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
1a540 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
1a550 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
1a560 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
1a570 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1a580 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
1a590 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
1a5a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a5b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1a5c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1a5d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1a5e0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
1a5f0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1a600 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
1a610 6e 74 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  nt value to the 
1a620 63 75 72 72 65 6e 74 20 53 51 4c 20 66 75 6e 63  current SQL func
1a630 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68  tion.** call, wh
1a640 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1a650 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 49  ond parameter. I
1a660 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68  f no meta-data h
1a670 61 73 20 62 65 65 6e 20 73 65 74 20 66 6f 72 0a  as been set for.
1a680 2a 2a 20 74 68 61 74 20 76 61 6c 75 65 2c 20 74  ** that value, t
1a690 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
1a6a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
1a6b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1a6c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
1a6d0 69 73 20 75 73 65 64 20 74 6f 20 61 73 73 6f 63  is used to assoc
1a6e0 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
1a6f0 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75  ith an SQL.** fu
1a700 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1a710 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1a720 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1a730 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61  r to the meta-da
1a740 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f  ta.** to be asso
1a750 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a760 4e 74 68 20 75 73 65 72 20 66 75 6e 63 74 69 6f  Nth user functio
1a770 6e 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  n argument value
1a780 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20  . The fourth.** 
1a790 70 61 72 61 6d 65 74 65 72 20 73 70 65 63 69 66  parameter specif
1a7a0 69 65 73 20 61 20 64 65 73 74 72 75 63 74 6f 72  ies a destructor
1a7b0 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 63 61   that will be ca
1a7c0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 61  lled on the meta
1a7d0 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65  -.** data pointe
1a7e0 72 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20  r to release it 
1a7f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1a800 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 20 49  nger required. I
1a810 66 20 74 68 65 20 0a 2a 2a 20 64 65 73 74 72 75  f the .** destru
1a820 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74  ctor is NULL, it
1a830 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e   is not invoked.
1a840 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
1a850 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73  ce, meta-data is
1a860 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
1a870 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
1a880 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
1a890 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
1a8a0 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
1a8b0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
1a8c0 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
1a8d0 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
1a8e0 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
1a8f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1a900 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
1a910 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
1a920 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
1a930 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1a940 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
1a950 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
1a960 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
1a970 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
1a980 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
1a990 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
1a9a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1a9b0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
1a9c0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
1a9d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1a9e0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
1a9f0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
1aa00 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
1aa10 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
1aa20 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ial value for th
1aa30 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
1aa40 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
1aa50 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
1aa60 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
1aa70 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
1aa80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
1aa90 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
1aaa0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
1aab0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
1aac0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
1aad0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
1aae0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
1aaf0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
1ab00 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
1ab10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ab20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
1ab30 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  he .** SQLITE_TR
1ab40 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
1ab50 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
1ab60 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
1ab70 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
1ab80 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
1ab90 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
1aba0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
1abb0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1abc0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
1abd0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
1abe0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
1abf0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
1ac00 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
1ac10 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
1ac20 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
1ac30 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
1ac40 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
1ac50 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
1ac60 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1ac70 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
1ac80 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
1ac90 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
1aca0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
1acb0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
1acc0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
1acd0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
1ace0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
1acf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1ad00 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
1ad10 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
1ad20 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
1ad30 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1ad40 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
1ad50 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
1ad60 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
1ad70 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
1ad80 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
1ad90 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
1ada0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1adb0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
1adc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1add0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
1ade0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
1adf0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
1ae00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
1ae10 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
1ae20 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ke the .** [sqli
1ae30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1ae40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20  sqlite3_bind_*] 
1ae50 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1ae60 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  ons used.** to b
1ae70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
1ae80 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
1ae90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1aea0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
1aeb0 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  o the.** [sqlite
1aec0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
1aed0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63  lite3_bind_* doc
1aee0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a  umentation] for.
1aef0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
1af00 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1af10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
1af20 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
1af30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
1af40 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
1af50 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
1af60 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
1af70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
1af80 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20  w an exception. 
1af90 20 54 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65   The.** paramete
1afa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
1afb0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
1afc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1afd0 72 6f 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68  ror16().** is th
1afe0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
1aff0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1b000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
1b010 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61  sult_toobig() ca
1b020 75 73 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  use the function
1b030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1b040 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20  ** to throw and 
1b050 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
1b060 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
1b070 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
1b080 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e  g.** to represen
1b090 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  t..**.** These r
1b0a0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
1b0b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
1b0c0 69 6e 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  in the same thre
1b0d0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
1b0e0 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
1b0f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73  ated with the [s
1b100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
1b110 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64  pointer..*/.void
1b120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b130 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
1b140 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1b150 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1b160 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
1b170 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
1b180 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
1b190 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
1b1a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1b1b0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
1b1c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1b1d0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
1b1e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b1f0 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
1b200 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1b210 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
1b220 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1b230 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
1b240 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b250 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
1b260 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
1b270 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
1b280 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
1b290 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
1b2a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b2b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1b2c0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
1b2d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1b2e0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
1b2f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b300 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
1b310 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
1b320 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b330 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
1b340 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1b350 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
1b360 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1b370 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b380 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1b390 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
1b3a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1b3b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
1b3c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b3d0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
1b3e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
1b3f0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
1b400 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
1b410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b420 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
1b430 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
1b440 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
1b450 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
1b460 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
1b470 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
1b480 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
1b490 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
1b4a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
1b4b0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1b4c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
1b4d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b4e0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
1b4f0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
1b500 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  es.**.** These f
1b510 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
1b520 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
1b530 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
1b540 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   to the.** [sqli
1b550 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65  te3*] handle spe
1b560 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
1b570 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a  rst argument. .*
1b580 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
1b590 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
1b5a0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
1b5b0 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
1b5c0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
1b5d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
1b5e0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
1b5f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1b600 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
1b610 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
1b620 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
1b630 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1b640 6f 6e 31 36 28 29 2e 20 20 49 6e 20 61 6c 6c 20  on16().  In all 
1b650 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
1b660 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
1b670 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
1b680 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
1b690 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
1b6a0 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
1b6b0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
1b6c0 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
1b6d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
1b6e0 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  6LE] or [SQLITE_
1b6f0 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
1b700 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
1b710 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
1b720 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
1b730 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
1b740 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
1b750 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
1b760 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
1b770 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20  ittle-endian or 
1b780 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
1b790 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  n respectively. 
1b7a0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
1b7b0 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
1b7c0 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
1b7d0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
1b7e0 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
1b7f0 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
1b800 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
1b810 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
1b820 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
1b830 66 20 55 54 46 31 36 20 69 6e 20 74 68 65 20 6e  f UTF16 in the n
1b840 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b850 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d   of the host com
1b860 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  puter..**.** A p
1b870 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
1b880 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
1b890 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
1b8a0 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
1b8b0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ** argument. If 
1b8c0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
1b8d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1b8e0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
1b8f0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
1b900 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
1b910 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
1b920 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68  t anymore). Each
1b930 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a   time the user.*
1b940 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  * supplied funct
1b950 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
1b960 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63  it is passed a c
1b970 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b980 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
1b990 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1b9a0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
1b9b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
1b9c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
1b9d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1b9e0 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20  () as its first 
1b9f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ba00 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
1ba10 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
1ba20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f  user-supplied ro
1ba30 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
1ba40 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
1ba50 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
1ba60 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70  [length, data] p
1ba70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
1ba80 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
1ba90 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
1baa0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
1bab0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
1bac0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
1bad0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
1bae0 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 72  stered. The user
1baf0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
1bb00 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
1bb10 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
1bb20 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73  e if.** the firs
1bb30 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
1bb40 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
1bb50 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1bb60 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73   the second.** s
1bb70 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
1bb80 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
1bb90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bba0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1bbb0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
1bbc0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
1bbd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
1bbe0 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74  * excapt that it
1bbf0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
1bc00 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
1bc10 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
1bc20 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
1bc30 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
1bc40 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
1bc50 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
1bc60 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
1bc70 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
1bc80 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
1bc90 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
1bca0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
1bcb0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
1bcc0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1bcd0 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e  v2().  Collation
1bce0 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
1bcf0 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
1bd00 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
1bd10 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
1bd20 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
1bd30 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
1bd40 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
1bd50 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
1bd60 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
1bd70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1bd80 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
1bd90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
1bda0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1bdb0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
1bdc0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1bdd0 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  d.** subject to 
1bde0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1bdf0 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 20   releases.  The 
1be00 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20  other collation 
1be10 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63  creation.** func
1be20 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c 65  tions are stable
1be30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1be40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1be50 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
1be60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1be70 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1be80 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1be90 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1bea0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1beb0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1bec0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
1bed0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1bee0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
1bef0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
1bf00 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
1bf10 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
1bf20 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
1bf30 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
1bf40 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
1bf50 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
1bf60 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
1bf70 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
1bf80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
1bf90 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
1bfa0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
1bfb0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
1bfc0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1bfd0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
1bfe0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
1bff0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1c000 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
1c010 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
1c020 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
1c030 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
1c040 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  s.**.** To avoid
1c050 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
1c060 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
1c070 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
1c080 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
1c090 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
1c0a0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
1c0b0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
1c0c0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
1c0d0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c0e0 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c  handle to be cal
1c0f0 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
1c100 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
1c110 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a  ion sequence is.
1c120 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ** required..**.
1c130 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
1c140 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
1c150 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c160 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c170 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
1c180 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
1c190 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
1c1a0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
1c1b0 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
1c1c0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
1c1d0 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71   in UTF-8. If sq
1c1e0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
1c1f0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
1c200 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a  ed, the names.**
1c210 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
1c220 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
1c230 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c240 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  er. A call to ei
1c250 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ther.** function
1c260 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
1c270 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
1c280 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1c290 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c2a0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
1c2b0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
1c2c0 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
1c2d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1c2e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
1c2f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
1c300 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1c310 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c320 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  6(). The second 
1c330 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1c340 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
1c350 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  le. The third ar
1c360 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
1c370 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
1c380 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1c390 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
1c3a0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
1c3b0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
1c3c0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
1c3d0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
1c3e0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
1c3f0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 65  on required. The
1c400 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1c410 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
1c420 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
1c430 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1c440 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
1c450 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c460 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
1c470 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
1c480 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
1c490 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1c4a0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
1c4b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1c4c0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
1c4d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1c4e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
1c4f0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1c500 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1c510 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
1c520 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
1c530 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1c540 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1c550 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
1c560 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1c570 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
1c580 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1c590 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
1c5a0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
1c5b0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
1c5c0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
1c5d0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
1c5e0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
1c5f0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
1c600 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
1c610 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
1c620 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
1c630 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
1c640 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1c650 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1c660 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1c670 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1c680 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1c690 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1c6a0 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
1c6b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1c6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1c6d0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
1c6e0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
1c6f0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
1c700 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
1c710 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
1c720 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
1c730 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
1c740 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
1c750 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
1c760 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
1c770 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
1c780 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
1c790 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
1c7a0 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
1c7b0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
1c7c0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
1c7d0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
1c7e0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
1c7f0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
1c800 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
1c810 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
1c820 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
1c830 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
1c840 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1c850 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1c860 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
1c870 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
1c880 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
1c890 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
1c8a0 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
1c8b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1c8c0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
1c8d0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
1c8e0 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  me.**.** This fu
1c8f0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
1c900 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
1c910 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
1c920 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65  ution.** a numbe
1c930 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
1c940 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
1c950 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
1c960 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
1c970 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
1c980 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
1c990 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
1c9a0 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
1c9b0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
1c9c0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
1c9d0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
1c9e0 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
1c9f0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
1ca00 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
1ca10 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1ca20 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72  p actually .** r
1ca30 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
1ca40 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1ca50 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
1ca60 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
1ca70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
1ca80 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
1ca90 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
1caa0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
1cab0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1cac0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
1cad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
1cae0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
1caf0 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
1cb00 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
1cb10 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
1cb20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20 74  Files.**.** If t
1cb30 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
1cb40 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
1cb50 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
1cb60 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
1cb70 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
1cb80 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f  r (a.ka. directo
1cb90 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
1cba0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
1cbb0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
1cbc0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
1cbd0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
1cbe0 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
1cbf0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c  riable.** is NUL
1cc00 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
1cc10 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65  SQLite does a se
1cc20 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
1cc30 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72  opriate temporar
1cc40 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74  y.** file direct
1cc50 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
1cc60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64   not safe to mod
1cc70 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
1cc80 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73  e once a databas
1cc90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1cca0 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  has been opened.
1ccb0 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64    It is intended
1ccc0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
1ccd0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
1cce0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
1ccf0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
1cd00 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
1cd10 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
1cd20 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
1cd30 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20   have been call 
1cd40 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  and remain uncha
1cd50 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e  nged thereafter.
1cd60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1cd70 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
1cd80 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
1cd90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cda0 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66    Test To See If
1cdb0 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73   The Database Is
1cdc0 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20   In Auto-Commit 
1cdd0 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20  Mode.**.** Test 
1cde0 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 20 6f  to see whether o
1cdf0 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62 61  r not the databa
1ce00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1ce10 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
1ce20 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e 20  * mode.  Return 
1ce30 54 52 55 45 20 69 66 20 69 74 20 69 73 20 61 6e  TRUE if it is an
1ce40 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20  d FALSE if not. 
1ce50 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
1ce60 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
1ce70 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
1ce80 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  t is disabled by
1ce90 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d 65   a BEGIN stateme
1cea0 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65 64  nt and reenabled
1ceb0 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74 20  .** by the next 
1cec0 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41  COMMIT or ROLLBA
1ced0 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  CK..**.** If cer
1cee0 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
1cef0 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
1cf00 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1cf10 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
1cf20 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
1cf30 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  ns (errors inclu
1cf40 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
1cf50 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
1cf60 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  R], .** [SQLITE_
1cf70 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
1cf80 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
1cf90 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
1cfa0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
1cfb0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
1cfc0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1cfd0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
1cfe0 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
1cff0 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74  ind out if SQLit
1d000 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
1d010 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
1d020 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
1d030 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
1d040 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
1d050 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
1d060 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
1d070 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
1d080 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
1d090 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1d0a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
1d0b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1d0c0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
1d0d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
1d0e0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
1d0f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d100 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
1d110 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1d120 20 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64   CAPI3REF:  Find
1d130 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
1d140 6e 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20  ndle Associated 
1d150 57 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20  With A Prepared 
1d160 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
1d170 52 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  Return the [sqli
1d180 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
1d190 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61  andle to which a
1d1a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
1d1b0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
1d1c0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
1d1d0 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20  .** This is the 
1d1e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61  same database ha
1d1f0 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a  ndle that was.**
1d200 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1d210 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
1d220 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d230 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1d240 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73  s.** that was us
1d250 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65  ed to create the
1d260 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1d270 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
1d280 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
1d290 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
1d2a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f  ite3_stmt*);.../
1d2b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1d2c0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
1d2d0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
1d2e0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1d2f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  These routines.*
1d300 2a 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  * register callb
1d310 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  ack functions to
1d320 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1d330 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
1d340 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74  on.** is committ
1d350 65 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63  ed or rolled bac
1d360 6b 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67  k.  The pArg arg
1d370 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
1d380 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68  through.** to th
1d390 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20  e callback.  If 
1d3a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
1d3b0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
1d3c0 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72  nction .** retur
1d3d0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1d3e0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
1d3f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
1d400 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
1d410 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
1d420 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
1d430 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
1d440 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69  its pArg value i
1d450 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f  s returned..** O
1d460 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
1d470 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1d480 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
1d490 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
1d4a0 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
1d4b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
1d4c0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
1d4d0 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
1d4e0 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
1d4f0 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72   have been .** r
1d500 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
1d510 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
1d520 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
1d530 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
1d540 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
1d550 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
1d560 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
1d570 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54  back to occur. T
1d580 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1d590 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
1d5a0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
1d5b0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
1d5c0 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20   rolled.** back 
1d5d0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
1d5e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d5f0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1d600 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72   These are exper
1d610 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
1d620 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65  es and are subje
1d630 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f  ct to change..*/
1d640 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
1d650 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
1d660 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
1d670 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
1d680 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
1d690 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
1d6a0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
1d6b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1d6c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
1d6d0 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
1d6e0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1d6f0 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20  *.** Register a 
1d700 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d710 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  n with the datab
1d720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1d730 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
1d740 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d   .** first argum
1d750 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ent to be invoke
1d760 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
1d770 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
1d780 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
1d790 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
1d7a0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
1d7b0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d7c0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68   function for th
1d7d0 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62  e same .** datab
1d7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1d7f0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
1d800 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1d810 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
1d820 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
1d830 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
1d840 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73  hen a .** row is
1d850 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
1d860 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54  ed or deleted. T
1d870 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d880 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
1d890 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f  k is.** a copy o
1d8a0 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
1d8b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1d8c0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54  update_hook(). T
1d8d0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
1d8e0 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ck .** argument 
1d8f0 69 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45  is one of SQLITE
1d900 5f 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f  _INSERT, SQLITE_
1d910 44 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45  DELETE or SQLITE
1d920 5f 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69  _UPDATE, dependi
1d930 6e 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65  ng.** on the ope
1d940 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
1d950 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
1d960 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54  to be invoked. T
1d970 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a  he third and .**
1d980 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1d990 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
1d9a0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
1d9b0 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  rs to the databa
1d9c0 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65  se and .** table
1d9d0 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
1d9e0 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
1d9f0 77 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  w. The final cal
1da00 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
1da10 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64  is .** the rowid
1da20 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20   of the row. In 
1da30 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
1da40 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
1da50 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a  he rowid after .
1da60 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61  ** the update ta
1da70 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
1da80 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
1da90 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
1daa0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
1dab0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
1dac0 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
1dad0 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
1dae0 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
1daf0 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  nce)..**.** If a
1db00 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
1db10 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
1db20 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70  egistered, its p
1db30 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74  Arg value is ret
1db40 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77  urned..** Otherw
1db50 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
1db60 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  rned..*/.void *s
1db70 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
1db80 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
1db90 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
1dba0 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
1dbb0 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
1dbc0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
1dbd0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
1dbe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
1dbf0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1dc00 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
1dc10 68 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  he.**.** This ro
1dc20 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
1dc30 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
1dc40 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
1dc50 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
1dc60 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
1dc70 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
1dc80 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f  n connections to
1dc90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1dca0 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69  se..** Sharing i
1dcb0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1dcc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
1dcd0 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  e and disabled i
1dce0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  f the argument.*
1dcf0 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  * is false..**.*
1dd00 2a 20 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53  * Beginning in S
1dd10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1dd20 35 2e 30 2c 20 63 61 63 68 65 20 73 68 61 72 69  5.0, cache shari
1dd30 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
1dd40 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f  d disabled.** fo
1dd50 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
1dd60 65 73 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76  ess.  In prior v
1dd70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1dd80 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a  e, sharing was.*
1dd90 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
1dda0 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
1ddb0 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
1ddc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
1ddd0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
1dde0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
1ddf0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
1de00 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
1de10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1de20 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1de30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
1de40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
1de50 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
1de60 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
1de70 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
1de80 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
1de90 20 6d 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a   mode that was.*
1dea0 2a 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  * in effect at t
1deb0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
1dec0 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
1ded0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
1dee0 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
1def0 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
1df00 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  e.  When shared.
1df10 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1df20 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
1df30 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
1df40 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
1df50 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
1df60 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
1df70 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
1df80 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
1df90 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1dfa0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
1dfb0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
1dfc0 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
1dfd0 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
1dfe0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49  fully.  An [SQLI
1dff0 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
1e000 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74   code].** is ret
1e010 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
1e020 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61  .**.** Shared ca
1e030 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
1e040 62 79 20 64 65 66 61 75 6c 74 2e 20 20 42 75 74  by default.  But
1e050 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
1e060 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
1e070 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1e080 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
1e090 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
1e0a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1e0b0 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
1e0c0 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
1e0d0 6c 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ly..*/.int sqlit
1e0e0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1e0f0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
1e100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41  .** CAPI3REF:  A
1e110 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
1e120 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
1e130 20 41 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   Attempt to free
1e140 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70   N bytes of heap
1e150 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
1e160 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
1e170 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ntial.** memory 
1e180 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64  allocations held
1e190 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
1e1a0 20 6c 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c   library (exampl
1e1b0 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73  e: memory .** us
1e1c0 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
1e1d0 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
1e1e0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
1e1f0 65 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e)..*/.int sqlit
1e200 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
1e210 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
1e220 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65  API3REF:  Impose
1e230 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
1e240 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63   Size.**.** Plac
1e250 65 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  e a "soft" limit
1e260 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
1e270 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
1e280 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
1e290 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ted.** by SQLite
1e2a0 2e 20 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  .  If an interna
1e2b0 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
1e2c0 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68  requested .** th
1e2d0 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  at would exceed 
1e2e0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6c 69  the specified li
1e2f0 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
1e300 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
1e310 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e  is.** invoked on
1e320 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
1e330 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
1e340 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
1e350 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1e360 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s made..**.** Th
1e370 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
1e380 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73  d "soft", becaus
1e390 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65  e if [sqlite3_re
1e3a0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
1e3b0 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73  cannot.** free s
1e3c0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1e3d0 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
1e3e0 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
1e3f0 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
1e400 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
1e410 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
1e420 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
1e430 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
1e440 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  .**.** A negativ
1e450 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
1e460 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
1e470 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
1e480 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
1e490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
1e4a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
1e4b0 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
1e4c0 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
1e4d0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
1e4e0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
1e4f0 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
1e500 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
1e510 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
1e520 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
1e530 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
1e540 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
1e550 2e 20 20 42 75 74 20 69 66 20 69 74 0a 2a 2a 20  .  But if it.** 
1e560 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 72 65 64  is unable to red
1e570 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  uce memory usage
1e580 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
1e590 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 69 6f 6e  limit, execution
1e5a0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
1e5b0 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
1e5c0 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
1e5d0 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
1e5e0 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63  e limit is .** c
1e5f0 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
1e600 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
1e610 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
1e620 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1e630 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1e640 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   this routine on
1e650 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74  ly constrained t
1e660 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
1e670 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67  ocated by a sing
1e680 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20  le thread - the 
1e690 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
1e6a0 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e  hich this routin
1e6b0 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69  e.** runs.  Begi
1e6c0 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
1e6d0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1e6e0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
1e6f0 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69  imit is.** appli
1e700 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ed to all thread
1e710 73 2e 20 20 54 68 65 20 76 61 6c 75 65 20 73 70  s.  The value sp
1e720 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20  ecified for the 
1e730 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
1e740 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62  ** is an upper b
1e750 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61  ound on the tota
1e760 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1e770 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ion for all thre
1e780 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73  ads.  In.** vers
1e790 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
1e7a0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
1e7b0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
1e7c0 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
1e7d0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
1e7e0 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
1e7f0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
1e800 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
1e810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
1e820 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
1e830 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
1e840 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
1e850 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
1e860 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
1e870 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
1e880 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
1e890 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
1e8a0 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
1e8b0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
1e8c0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
1e8d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1e8e0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
1e8f0 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
1e900 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
1e910 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1e920 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
1e930 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
1e940 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
1e950 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
1e960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e970 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
1e980 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1e990 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
1e9a0 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
1e9b0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
1e9c0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
1e9d0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
1e9e0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
1e9f0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
1ea00 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
1ea10 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
1ea20 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
1ea30 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
1ea40 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
1ea50 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
1ea60 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
1ea70 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
1ea80 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
1ea90 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
1eaa0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
1eab0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
1eac0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1ead0 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
1eae0 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
1eaf0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
1eb00 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
1eb10 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
1eb20 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
1eb30 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
1eb40 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
1eb50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1eb60 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
1eb70 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
1eb80 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
1eb90 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
1eba0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
1ebb0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ebc0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
1ebd0 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
1ebe0 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
1ebf0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
1ec00 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
1ec10 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
1ec20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
1ec30 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64  tion is ommitted
1ec40 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
1ec50 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
1ec60 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
1ec70 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
1ec80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ec90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1eca0 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
1ecb0 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
1ecc0 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
1ecd0 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
1ece0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
1ecf0 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
1ed00 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
1ed10 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
1ed20 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
1ed30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
1ed40 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
1ed50 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
1ed60 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
1ed70 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
1ed80 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1ed90 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1eda0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
1edb0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
1edc0 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
1edd0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1ede0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1edf0 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
1ee00 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1ee10 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
1ee20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
1ee30 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
1ee40 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
1ee50 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
1ee60 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
1ee70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1ee80 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
1ee90 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
1eea0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
1eeb0 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
1eec0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
1eed0 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
1eee0 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
1eef0 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
1ef00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1ef10 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
1ef20 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
1ef30 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
1ef40 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
1ef50 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
1ef60 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
1ef70 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
1ef80 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
1ef90 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1efa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
1efb0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
1efc0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1efd0 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
1efe0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
1eff0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1f000 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
1f010 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
1f020 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
1f030 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
1f040 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
1f050 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
1f060 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
1f070 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1f080 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
1f090 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
1f0a0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
1f0b0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
1f0c0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
1f0d0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
1f0e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1f0f0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
1f100 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
1f110 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
1f120 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
1f130 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
1f140 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
1f150 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
1f160 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
1f170 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
1f180 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
1f190 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
1f1a0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
1f1b0 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
1f1c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
1f1d0 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
1f1e0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
1f1f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
1f200 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
1f210 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
1f220 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
1f230 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1f240 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
1f250 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1f260 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
1f270 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
1f280 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
1f290 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1f2a0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
1f2b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f2c0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
1f2d0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
1f2e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
1f2f0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
1f300 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
1f310 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
1f320 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
1f330 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
1f340 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
1f350 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
1f360 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
1f370 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
1f380 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
1f390 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
1f3a0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
1f3b0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
1f3c0 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
1f3d0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
1f3e0 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
1f3f0 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
1f400 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
1f410 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1f420 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
1f430 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
1f440 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
1f450 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
1f460 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
1f470 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
1f480 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
1f490 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
1f4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1f4b0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
1f4c0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
1f4d0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
1f4e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f4f0 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
1f500 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70  ion.**.** Attemp
1f510 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c  t to load an SQL
1f520 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
1f530 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
1f540 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a  in the file.** z
1f550 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72 79  File.  The entry
1f560 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
1f570 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30    zProc may be 0
1f580 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1f590 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
1f5a0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65  e entry point de
1f5b0 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
1f5c0 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
1f5d0 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  t"..**.** Return
1f5e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1f5f0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
1f600 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
1f610 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
1f620 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ng..**.** If an 
1f630 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
1f640 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
1f650 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70   0, then fill *p
1f660 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
1f670 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
1f680 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ext.  The callin
1f690 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
1f6a0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
1f6b0 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67  ry.** by calling
1f6c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f6d0 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69  ]..**.** Extensi
1f6e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
1f6f0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
1f700 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1f710 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1f720 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  )].** prior to c
1f730 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20  alling this API 
1f740 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  or an error will
1f750 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
1f760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
1f770 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
1f780 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f790 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
1f7a0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
1f7b0 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
1f7c0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
1f7d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
1f7e0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
1f7f0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
1f800 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
1f810 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
1f820 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
1f830 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
1f840 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
1f850 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
1f860 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
1f870 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
1f880 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
1f890 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
1f8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f8b0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1f8c0 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
1f8d0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  ding.**.** So as
1f8e0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
1f8f0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
1f900 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
1f910 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
1f920 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
1f930 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
1f940 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
1f950 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
1f960 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
1f970 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
1f980 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
1f990 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
1f9a0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
1f9b0 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
1f9c0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
1f9d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
1f9e0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
1f9f0 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49  n and.** off.  I
1fa00 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
1fa10 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ult.  See ticket
1fa20 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61   #1863..**.** Ca
1fa30 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1fa40 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
1fa50 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
1fa60 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
1fa70 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
1fa80 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
1fa90 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
1faa0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
1fab0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1fac0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
1fad0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
1fae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1faf0 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
1fb00 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
1fb10 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
1fb20 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67  ension.**.** Reg
1fb30 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73 69  ister an extensi
1fb40 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
1fb50 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  hat is automatic
1fb60 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ally invoked.** 
1fb70 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64  whenever a new d
1fb80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fb90 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69  on is opened usi
1fba0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ng.** [sqlite3_o
1fbb0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1fbc0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
1fbd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fbe0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  )]..**.** This A
1fbf0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
1fc00 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
1fc10 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
1fc20 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
1fc30 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
1fc40 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
1fc50 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
1fc60 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
1fc70 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
1fc80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
1fc90 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65  .**.** Duplicate
1fca0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20   extensions are 
1fcb0 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c  detected so call
1fcc0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1fcd0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
1fce0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
1fcf0 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61   extension is ha
1fd00 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rmless..**.** Th
1fd10 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1fd20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1fd30 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
1fd40 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74  an array.** that
1fd50 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
1fd60 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20  m malloc().  If 
1fd70 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79  you run a memory
1fd80 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72   leak.** checker
1fd90 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d   on your program
1fda0 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20   and it reports 
1fdb0 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f  a leak because o
1fdc0 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c  f this.** array,
1fdd0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71   then invoke [sq
1fde0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
1fdf0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
1fe00 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f  ior.** to shutdo
1fe10 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
1fe20 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 74  emory..**.** Aut
1fe30 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
1fe40 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61  s apply across a
1fe50 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  ll threads..**.*
1fe60 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1fe70 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
1fe80 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
1fe90 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
1fea0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
1feb0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
1fec0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
1fed0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
1fee0 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79  ion(void *xEntry
1fef0 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  Point);.../*.** 
1ff00 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1ff10 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
1ff20 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
1ff30 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70 72  * Disable all pr
1ff40 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1ff50 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78  red automatic ex
1ff60 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73 0a  tensions.  This.
1ff70 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
1ff80 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
1ff90 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74  all prior [sqlit
1ffa0 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74  e3_automatic_ext
1ffb0 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c  ension()].** cal
1ffc0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 63  ls..**.** This c
1ffd0 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74  all disabled aut
1ffe0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
1fff0 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73  s in all threads
20000 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20010 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69  erface is experi
20020 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
20030 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
20040 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e  or.** removal in
20050 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
20060 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
20070 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
20080 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
20090 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a  (void);.../*.***
200a0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
200b0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
200c0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
200d0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
200e0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
200f0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
20100 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
20110 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
20120 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
20130 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
20140 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
20150 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
20160 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
20170 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
20180 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
20190 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
201a0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
201b0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
201c0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
201d0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
201e0 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c  anism stablizes,
201f0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
20200 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
20210 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
20220 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
20230 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
20240 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
20250 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
20260 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
20270 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
20280 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
20290 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
202a0 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
202b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
202c0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
202d0 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
202e0 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
202f0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
20300 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
20310 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
20320 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20330 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
20340 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
20350 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20  .** A module is 
20360 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75  a class of virtu
20370 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68  al tables.  Each
20380 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e   module is defin
20390 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74  ed.** by an inst
203a0 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
203b0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e  owing structure.
203c0 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65    This structure
203d0 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73   consists.** mos
203e0 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
203f0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
20400 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
20410 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
20420 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
20430 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
20440 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
20450 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
20460 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
20470 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
20480 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
20490 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
204a0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
204b0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
204c0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
204d0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
204e0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
204f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
20500 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
20510 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
20520 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
20530 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
20540 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
20550 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
20560 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
20570 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
20580 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
20590 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
205a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
205b0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
205c0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
205d0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
205e0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
205f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
20600 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
20610 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
20620 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
20630 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
20640 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
20650 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
20660 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
20670 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
20680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
20690 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
206a0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
206b0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
206c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
206d0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
206e0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
206f0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
20700 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
20710 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
20720 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20730 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
20740 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
20750 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
20760 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
20770 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
20780 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
20790 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
207a0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
207b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
207c0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
207d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
207e0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
207f0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
20800 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
20810 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
20820 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
20830 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
20840 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
20850 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
20860 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
20870 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
20880 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
20890 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
208a0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
208b0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
208c0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
208d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
208e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
208f0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
20900 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
20910 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20  *ppArg);..  int 
20920 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
20930 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
20940 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
20950 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  );.};../*.** The
20960 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
20970 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
20980 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
20990 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
209a0 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
209b0 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
209c0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
209d0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
209e0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
209f0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
20a00 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
20a10 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
20a20 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
20a30 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
20a40 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
20a50 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
20a60 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
20a70 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
20a80 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
20a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
20aa0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
20ab0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
20ac0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
20ad0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
20ae0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
20af0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
20b00 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
20b10 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20  =, <, <=, >, or 
20b20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75  >=.  The particu
20b30 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
20b40 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
20b50 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
20b60 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
20b70 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
20b80 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
20b90 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
20ba0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
20bb0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
20bc0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
20bd0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
20be0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
20bf0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
20c00 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
20c10 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
20c20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
20c30 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
20c40 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
20c50 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
20c60 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
20c70 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
20c80 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
20c90 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
20ca0 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
20cb0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
20cc0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
20cd0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
20ce0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
20cf0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
20d00 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
20d10 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
20d20 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
20d30 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
20d40 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
20d50 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
20d60 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
20d70 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
20d80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
20d90 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
20da0 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
20db0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
20dc0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
20dd0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
20de0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
20df0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
20e00 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
20e10 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
20e20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
20e30 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
20e40 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
20e50 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
20e60 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
20e70 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
20e80 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
20e90 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
20ea0 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
20eb0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
20ec0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
20ed0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
20ee0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
20ef0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
20f00 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
20f10 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
20f20 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
20f30 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
20f40 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
20f50 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
20f60 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
20f70 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
20f80 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
20f90 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
20fa0 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
20fb0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
20fc0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
20fd0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
20fe0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
20ff0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
21000 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
21010 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
21020 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
21030 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
21040 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
21050 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
21060 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
21070 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
21080 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
21090 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
210a0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
210b0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
210c0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
210d0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
210e0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
210f0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
21100 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
21110 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
21120 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
21130 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
21140 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
21150 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
21160 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
21170 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
21180 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
21190 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
211a0 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
211b0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
211c0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
211d0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
211e0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
211f0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
21200 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
21210 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
21220 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
21230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
21240 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
21250 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
21260 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
21270 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
21280 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
21290 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
212a0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
212b0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
212c0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
212d0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
212e0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
212f0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
21300 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
21310 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
21320 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
21330 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
21340 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
21350 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
21360 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
21370 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
21380 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
21390 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
213a0 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
213b0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
213c0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
213d0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
213e0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
213f0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
21400 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
21410 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
21420 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
21430 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
21440 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
21450 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
21460 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
21470 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
21480 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
21490 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
214a0 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
214b0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
214c0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
214d0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
214e0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
214f0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
21500 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
21510 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
21520 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
21530 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
21540 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
21550 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
21560 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
21570 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
21580 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
21590 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
215a0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
215b0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
215c0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
215d0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
215e0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
215f0 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
21600 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
21610 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
21620 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
21630 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
21640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21650 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
21660 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
21670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
21680 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
21690 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
216a0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
216b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
216c0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
216d0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
216e0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
216f0 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
21700 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
21710 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
21720 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
21730 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
21740 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
21750 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
21760 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
21770 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
21780 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
21790 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
217a0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
217b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
217c0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
217d0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
217e0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
217f0 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
21800 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
21810 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
21820 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
21830 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21840 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
21850 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
21860 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
21870 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
21880 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
21890 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
218a0 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
218b0 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
218c0 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
218d0 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
218e0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
218f0 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
21900 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
21910 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
21920 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
21930 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
21940 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
21950 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
21960 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
21970 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
21980 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
21990 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
219a0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
219b0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
219c0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
219d0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
219e0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
219f0 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
21a00 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
21a10 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
21a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21a30 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
21a40 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
21a50 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
21a60 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
21a70 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
21a80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
21a90 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68  te_module() meth
21aa0 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63  od above,.** exc
21ab0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  ept that it allo
21ac0 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ws a destructor 
21ad0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73  function to be s
21ae0 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a  pecified. It is.
21af0 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70  ** even more exp
21b00 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74  erimental than t
21b10 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76  he rest of the v
21b20 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50  irtual tables AP
21b30 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  I..*/.int sqlite
21b40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
21b50 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
21b60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
21b70 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
21b80 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
21b90 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
21ba0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
21bb0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
21bc0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
21bd0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
21be0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
21bf0 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
21c00 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
21c10 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
21c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21c30 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
21c40 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
21c50 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
21c60 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
21c70 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
21c80 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
21c90 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65  */.);../*.** Eve
21ca0 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ry module implem
21cb0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
21cc0 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20  subclass of the 
21cd0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
21ce0 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69  ure.** to descri
21cf0 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  be a particular 
21d00 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
21d10 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75  module.  Each su
21d20 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
21d30 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
21d40 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
21d50 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
21d60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
21d70 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20   The.** purpose 
21d80 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
21d90 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
21da0 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
21db0 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a  hat are common.*
21dc0 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  * to all module 
21dd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
21de0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
21df0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
21e00 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
21e10 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
21e20 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
21e30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
21e40 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
21e50 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
21e60 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
21e70 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
21e80 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
21e90 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
21ea0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21eb0 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20  free().** prior 
21ec0 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
21ed0 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
21ee0 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65  rMsg.  After the
21ef0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
21f00 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75  * is delivered u
21f10 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20  p to the client 
21f20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
21f30 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
21f40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
21f50 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65   freed by sqlite
21f60 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65  3_free() and the
21f70 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77   zErrMsg field w
21f80 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20  ill be zeroed.  
21f90 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c  Note.** that sql
21fa0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
21fb0 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  nd sqlite3_free(
21fc0 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68  ) are used on th
21fd0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a  e zErrMsg field.
21fe0 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c  ** since virtual
21ff0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d   tables are comm
22000 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64  only implemented
22010 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74   in loadable ext
22020 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a  ensions which.**
22030 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63   do not have acc
22040 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50  ess to sqlite3MP
22050 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74  rintf() or sqlit
22060 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72  e3Free()..*/.str
22070 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
22080 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
22090 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
220a0 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
220b0 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
220c0 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
220d0 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
220e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
220f0 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
22100 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  y */.  char *zEr
22110 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
22120 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
22130 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
22140 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
22150 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
22160 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
22170 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
22180 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
22190 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
221a0 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  ./* Every module
221b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
221c0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
221d0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
221e0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
221f0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
22200 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
22210 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
22220 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64  ble and are used
22230 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
22240 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
22250 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
22260 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
22270 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d  g the.** xOpen m
22280 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
22290 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
222a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
222b0 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
222c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
222d0 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
222e0 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
222f0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
22300 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
22310 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
22320 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
22330 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
22340 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
22350 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
22360 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
22370 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
22380 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
22390 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
223a0 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
223b0 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
223c0 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
223d0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
223e0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
223f0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
22400 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
22410 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  */.};../*.** The
22420 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
22430 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66  nnect methods of
22440 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68   a module use th
22450 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
22460 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
22470 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
22480 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
22490 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
224a0 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
224b0 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
224c0 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
224d0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
224e0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
224f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
22500 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a  eateTable);../*.
22510 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
22520 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c  s can provide al
22530 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d  ternative implem
22540 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e  entations of fun
22550 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20  ctions.** using 
22560 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f  the xFindFunctio
22570 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67  n method.  But g
22580 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
22590 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
225a0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
225b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
225c0 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
225d0 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20   This API makes 
225e0 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65  sure a global ve
225f0 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74  rsion of a funct
22600 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69  ion with a parti
22610 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e  cular.** name an
22620 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  d number of para
22630 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20  meters exists.  
22640 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74  If no such funct
22650 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65  ion exists.** be
22660 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73  fore this API is
22670 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66   called, a new f
22680 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  unction is creat
22690 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  ed.  The impleme
226a0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
226b0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61  e new function a
226c0 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20  lways causes an 
226d0 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20  exception to be 
226e0 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74  thrown.  So.** t
226f0 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
22700 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20  is not good for 
22710 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65  anything by itse
22720 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a  lf.  Its only.**
22730 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62   purpose is to b
22740 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72  e a place-holder
22750 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
22760 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
22770 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74  .** by virtual t
22780 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ables..**.** Thi
22790 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20  s API should be 
227a0 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20  considered part 
227b0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
227c0 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a  able interface,.
227d0 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65  ** which is expe
227e0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62  rimental and sub
227f0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
22800 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
22810 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
22820 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
22830 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
22840 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
22850 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
22860 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
22870 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
22880 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
22890 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
228a0 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
228b0 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
228c0 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
228d0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
228e0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
228f0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
22900 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
22910 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
22920 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
22930 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
22940 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
22950 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
22960 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
22970 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
22980 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
22990 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
229a0 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
229b0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
229c0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
229d0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
229e0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
229f0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a  this comment..**
22a00 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
22a10 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
22a20 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
22a30 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
22a40 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ******.*/../*.**
22a50 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e   CAPI3REF: A Han
22a60 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42  dle To An Open B
22a70 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  LOB.**.** An ins
22a80 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
22a90 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74  lowing opaque st
22aa0 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64 20  ructure is used 
22ab0 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  to .** represent
22ac0 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e   an blob-handle.
22ad0 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20    A blob-handle 
22ae0 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a  is created by.**
22af0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
22b00 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72  pen()] and destr
22b10 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
22b20 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
22b30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
22b40 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
22b50 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
22b60 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
22b70 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
22b80 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
22b90 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
22ba0 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ions of the blob
22bb0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
22bc0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
22bd0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22be0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
22bf0 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74  e.** blob in byt
22c00 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
22c10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
22c20 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
22c30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22c40 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
22c50 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
22c60 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68  O.**.** Open a h
22c70 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f  andle to the blo
22c80 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f 77  b located in row
22c90 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a   iRow,, column z
22ca0 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c  Column, .** tabl
22cb0 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
22cc0 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74  base zDb. i.e. t
22cd0 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61  he same blob tha
22ce0 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65  t would.** be se
22cf0 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a  lected by:.**.**
22d00 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45   <pre>.**     SE
22d10 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f  LECT zColumn FRO
22d20 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45  M zDb.zTable WHE
22d30 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b  RE rowid = iRow;
22d40 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
22d50 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
22d60 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
22d70 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73  ero, the blob is
22d80 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20   opened for .** 
22d90 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
22da0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20  ccess. If it is 
22db0 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69  zero, the blob i
22dc0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
22dd0 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a  d .** access..**
22de0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
22df0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
22e00 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
22e10 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  new .** [sqlite3
22e20 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e  _blob | blob han
22e30 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20  dle] is written 
22e40 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f  to *ppBlob..** O
22e50 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
22e60 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
22e70 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76  ed and .** any v
22e80 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20  alue written to 
22e90 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e  *ppBlob should n
22ea0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68  ot be used by th
22eb0 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69  e caller..** Thi
22ec0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
22ed0 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e  the database-han
22ee0 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  dle error code a
22ef0 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
22f00 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
22f10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
22f20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
22f30 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
22f40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
22f50 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
22f60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
22f70 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
22f80 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
22f90 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
22fa0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
22fb0 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
22fc0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
22fd0 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
22fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43  .** CAPI3REF:  C
22ff0 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
23000 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61  le.**.** Close a
23010 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  n open [sqlite3_
23020 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64  blob | blob hand
23030 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  le]..*/.int sqli
23040 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
23050 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
23060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23070 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a    Return The Siz
23080 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
23090 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  B.**.** Return t
230a0 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
230b0 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63   of the blob acc
230c0 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
230d0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
230e0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
230f0 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20  ndle] passed as 
23100 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a  an argument..*/.
23110 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
23120 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
23130 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
23140 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44  API3REF:  Read D
23150 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20  ata From A BLOB 
23160 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a  Incrementally.**
23170 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
23180 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  n is used to rea
23190 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f  d data from an o
231a0 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
231b0 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
231c0 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c  dle] into a call
231d0 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66  er supplied buff
231e0 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f  er..** n bytes o
231f0 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
23200 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a  d into buffer.**
23210 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e   z from the open
23220 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20   blob, starting 
23230 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  at offset iOffse
23240 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
23250 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69  ess, SQLITE_OK i
23260 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
23270 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53  rwise, an .** [S
23280 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51  QLITE_ERROR | SQ
23290 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d  Lite error code]
232a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54   or an.** [SQLIT
232b0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
232c0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
232d0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
232e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
232f0 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65  blob_read(sqlite
23300 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a  3_blob *, void *
23310 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f  z, int n, int iO
23320 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
23330 41 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20  API3REF:  Write 
23340 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42  Data Into A BLOB
23350 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a   Incrementally.*
23360 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
23370 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
23380 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
23390 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
233a0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
233b0 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73  andle] from a us
233c0 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66  er supplied buff
233d0 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f  er..** n bytes o
233e0 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
233f0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
23400 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  r.** pointed to 
23410 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70  by z into the op
23420 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
23430 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
23440 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  set..**.** If th
23450 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  e [sqlite3_blob 
23460 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70  | blob-handle] p
23470 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
23480 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  st argument.** w
23490 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
234a0 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  r writing (the f
234b0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
234c0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
234d0 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20  open()].*** was 
234e0 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63  zero), this func
234f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
23500 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
23510 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
23520 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
23530 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
23540 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 74   of the blob, it
23550 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
23560 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
23570 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  the size of a bl
23580 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  ob using this AP
23590 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20  I. If.** offset 
235a0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
235b0 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f  than n bytes fro
235c0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
235d0 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49   blob, .** [SQLI
235e0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
235f0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
23600 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a  a is written..**
23610 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
23620 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
23630 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65  urned. Otherwise
23640 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  , an .** [SQLITE
23650 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20  _ERROR | SQLite 
23660 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
23670 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  n.** [SQLITE_IOE
23680 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
23690 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
236a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  s returned..*/.i
236b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
236c0 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
236d0 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
236e0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
236f0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
23700 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 74   CAPI3REF:  Virt
23710 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
23720 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20  Objects.**.** A 
23730 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
23740 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
23750 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
23760 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
23770 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
23780 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
23790 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
237a0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
237b0 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77  st builds come w
237c0 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  ith a.** single 
237d0 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74  default VFS that
237e0 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   is appropriate 
237f0 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d  for the host com
23800 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46  puter..** New VF
23810 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  Ses can be regis
23820 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69  tered and existi
23830 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ng VFSes can be 
23840 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  unregistered..**
23850 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   The following i
23860 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
23870 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  ovided..**.** Th
23880 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
23890 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
238a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
238b0 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
238c0 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20 4e 61  its.** name.  Na
238d0 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
238e0 73 69 74 69 76 65 2e 20 20 49 66 20 74 68 65 72  sitive.  If ther
238f0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
23900 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
23910 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49   is returned.  I
23920 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
23930 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
23940 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20 72  ult .** VFS is r
23950 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  eturned..**.** N
23960 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
23970 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
23980 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
23990 72 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20 6e 65  r().  Each.** ne
239a0 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
239b0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
239c0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
239d0 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68  ag is set..** Th
239e0 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
239f0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
23a00 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
23a10 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54  out injury..** T
23a20 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69  o make an existi
23a30 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20  ng VFS into the 
23a40 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67  default VFS, reg
23a50 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a  ister it again.*
23a60 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44  * with the makeD
23a70 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49  flt flag set.  I
23a80 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20  f two different 
23a90 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a  VFSes with the.*
23aa0 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  * same name are 
23ab0 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20  registered, the 
23ac0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
23ad0 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20  fined.  If a.** 
23ae0 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65  VFS is registere
23af0 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68  d with a name th
23b00 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  at is NULL or an
23b10 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a   empty string,.*
23b20 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
23b30 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
23b40 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73  ..** .** Unregis
23b50 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74  ter a VFS with t
23b60 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  he sqlite3_vfs_u
23b70 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65  nregister() inte
23b80 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65  rface..** If the
23b90 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
23ba0 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e  unregistered, an
23bb0 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f  other VFS is cho
23bc0 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65  sen as.** the de
23bd0 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69  fault.  The choi
23be0 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56  ce for the new V
23bf0 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  FS is arbitrary.
23c00 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
23c10 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
23c20 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
23c30 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
23c40 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
23c50 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  r(sqlite3_vfs*, 
23c60 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69  int makeDflt);.i
23c70 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  nt sqlite3_vfs_u
23c80 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  nregister(sqlite
23c90 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  3_vfs*);../*.** 
23ca0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65  CAPI3REF: Mutexe
23cb0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  s.**.** The SQLi
23cc0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
23cd0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  se routines for 
23ce0 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72  thread.** synchr
23cf0 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75  onization.  Thou
23d00 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65  gh they are inte
23d10 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  nded for interna
23d20 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
23d30 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69  te, code that li
23d40 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
23d50 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74  te is.** permitt
23d60 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66  ed to use any of
23d70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
23d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
23d90 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  e source code co
23da0 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20  ntains multiple 
23db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
23dc0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74  .** of these mut
23dd0 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e  ex routines.  An
23de0 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70   appropriate imp
23df0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
23e00 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d  s selected autom
23e10 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70  atically at comp
23e20 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66  ile-time.  The f
23e30 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c  ollowing.** impl
23e40 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20  ementations are 
23e50 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
23e60 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a   SQLite core:.**
23e70 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
23e80 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
23e90 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  OS2.** <li>   SQ
23ea0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
23eb0 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
23ec0 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a  ITE_MUTEX_W32.**
23ed0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
23ee0 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75  UTEX_NOOP.** </u
23ef0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
23f00 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69  ITE_MUTEX_NOOP i
23f10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
23f20 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e   a set of routin
23f30 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  es .** that does
23f40 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67   no real locking
23f50 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69   and is appropri
23f60 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 20 0a  ate for use in .
23f70 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65  ** a single-thre
23f80 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
23f90 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  .  The SQLITE_MU
23fa0 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49  TEX_OS2,.** SQLI
23fb0 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44  TE_MUTEX_PTHREAD
23fc0 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  , and SQLITE_MUT
23fd0 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74  EX_W32 implement
23fe0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70  ations.** are ap
23ff0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
24000 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78 2c  e on os/2, unix,
24010 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a 2a   and windows..**
24020 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69   .** If SQLite i
24030 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
24040 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  the SQLITE_MUTEX
24050 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65  _APPDEF preproce
24060 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65  ssor.** macro de
24070 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53  fined (with "-DS
24080 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
24090 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20  EF=1"), then no 
240a0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
240b0 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75  ntation is inclu
240c0 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ded with the lib
240d0 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75  rary.  The.** mu
240e0 74 65 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f  tex interface ro
240f0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
24100 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74 65 72  ere become exter
24110 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63 65  nal.** reference
24120 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  s in the SQLite 
24130 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68 69 63  library for whic
24140 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  h implementation
24150 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72 6f  s.** must be pro
24160 76 69 64 65 64 20 62 79 20 74 68 65 20 61 70 70  vided by the app
24170 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  lication.  This 
24180 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73 20  facility allows 
24190 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  an.** applicatio
241a0 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  n that links aga
241b0 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f 20 70  inst SQLite to p
241c0 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 6d  rovide its own m
241d0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
241e0 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 68  tation without h
241f0 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79 20  aving to modify 
24200 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
24210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24220 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
24230 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74   routine allocat
24240 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65  es a new.** mute
24250 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  x and returns a 
24260 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 20  pointer to it.  
24270 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  If it returns NU
24280 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73  LL.** that means
24290 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f   that a mutex co
242a0 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63  uld not be alloc
242b0 61 74 65 64 2e 20 20 53 51 4c 69 74 65 0a 2a 2a  ated.  SQLite.**
242c0 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73   will unwind its
242d0 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72   stack and retur
242e0 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 54 68 65  n an error.  The
242f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
24300 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
24310 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
24320 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
24330 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
24340 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
24350 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
24360 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
24370 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
24380 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
24390 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
243a0 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
243b0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
243c0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
243d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
243e0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
243f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
24400 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
24410 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
24420 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f 75 6c  ATIC_LRU.** </ul
24430 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  >.**.** The firs
24440 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  t two constants 
24450 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
24460 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
24470 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
24480 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d  utex.  The new m
24490 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76  utex is recursiv
244a0 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  e when SQLITE_MU
244b0 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
244c0 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74   is used but not
244d0 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20   necessarily so 
244e0 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
244f0 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a  X_FAST is used..
24500 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
24510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
24520 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
24530 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
24540 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
24550 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
24560 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
24570 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
24580 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
24590 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65 20 77  o.  But SQLite w
245a0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74  ill only request
245b0 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74   a recursive mut
245c0 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77  ex in.** cases w
245d0 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e  here it really n
245e0 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20 61 20  eeds one.  If a 
245f0 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
24600 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
24610 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
24620 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
24630 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
24640 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
24650 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
24660 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
24670 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
24680 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
24690 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 74 68  T..**.** The oth
246a0 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
246b0 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
246c0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65  _mutex_alloc() e
246d0 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20  ach return.** a 
246e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61  pointer to a sta
246f0 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20  tic preexisting 
24700 6d 75 74 65 78 2e 20 20 46 6f 75 72 20 73 74 61  mutex.  Four sta
24710 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a  tic mutexes are.
24720 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63  ** used by the c
24730 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f  urrent version o
24740 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72  f SQLite.  Futur
24750 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
24760 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20  Lite.** may add 
24770 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
24780 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74  c mutexes.  Stat
24790 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66  ic mutexes are f
247a0 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
247b0 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c  se by SQLite onl
247c0 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  y.  Applications
247d0 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65   that use SQLite
247e0 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a   mutexes should.
247f0 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20  ** use only the 
24800 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20  dynamic mutexes 
24810 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49  returned by SQLI
24820 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72  TE_MUTEX_FAST or
24830 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
24840 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a  _RECURSIVE..**.*
24850 2a 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f  * Note that if o
24860 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69  ne of the dynami
24870 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65  c mutex paramete
24880 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58  rs (SQLITE_MUTEX
24890 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49  _FAST.** or SQLI
248a0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
248b0 56 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e  VE) is used then
248c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
248d0 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e  lloc().** return
248e0 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75  s a different mu
248f0 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c  tex on every cal
24900 6c 2e 20 20 42 75 74 20 66 6f 72 20 74 68 65 20  l.  But for the 
24910 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78  static .** mutex
24920 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65   types, the same
24930 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e   mutex is return
24940 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ed on every call
24950 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65   that has.** the
24960 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65   same type numbe
24970 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
24980 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
24990 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f  ) routine deallo
249a0 63 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73  cates a previous
249b0 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ly.** allocated 
249c0 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20  dynamic mutex.  
249d0 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
249e0 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
249f0 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
24a00 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
24a10 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64  llocates.  The d
24a20 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d  ynamic mutexes m
24a30 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 20 0a 2a  ust not be in .*
24a40 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20  * use when they 
24a50 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
24a60 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20    Attempting to 
24a70 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61  deallocate a sta
24a80 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73  tic.** mutex res
24a90 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
24aa0 64 20 62 65 68 61 76 69 6f 72 2e 20 20 53 51 4c  d behavior.  SQL
24ab0 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f  ite never deallo
24ac0 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69  cates.** a stati
24ad0 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 54  c mutex..**.** T
24ae0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
24af0 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c  _enter() and sql
24b00 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
24b10 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
24b20 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20  t.** to enter a 
24b30 6d 75 74 65 78 2e 20 20 49 66 20 61 6e 6f 74 68  mutex.  If anoth
24b40 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72  er thread is alr
24b50 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20  eady within the 
24b60 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65  mutex,.** sqlite
24b70 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20  3_mutex_enter() 
24b80 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73  will block and s
24b90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
24ba0 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
24bb0 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  * SQLITE_BUSY.  
24bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
24bd0 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63  x_try() interfac
24be0 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
24bf0 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  _OK.** upon succ
24c00 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 4d  essful entry.  M
24c10 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
24c20 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d 55 54 45  sing SQLITE_MUTE
24c30 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 0a  X_RECURSIVE can.
24c40 2a 2a 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  ** be entered mu
24c50 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
24c60 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
24c70 20 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20    In such cases 
24c80 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75  the,.** mutex mu
24c90 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20  st be exited an 
24ca0 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  equal number of 
24cb0 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f  times before ano
24cc0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63  ther thread.** c
24cd0 61 6e 20 65 6e 74 65 72 2e 20 20 49 66 20 74 68  an enter.  If th
24ce0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72  e same thread tr
24cf0 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79  ies to enter any
24d00 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f 66 20 6d   other kind of m
24d10 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 74 68 61  utex.** more tha
24d20 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61  n once, the beha
24d30 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24d40 64 2e 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  d.   SQLite will
24d50 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a   never exhibit.*
24d60 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20  * such behavior 
24d70 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f  in its own use o
24d80 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a  f mutexes..**.**
24d90 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 65   Some systems (e
24da0 78 3a 20 77 69 6e 64 6f 77 73 39 35 29 20 64 6f  x: windows95) do
24db0 20 6e 6f 74 20 74 68 65 20 6f 70 65 72 61 74 69   not the operati
24dc0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  on implemented b
24dd0 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  y.** sqlite3_mut
24de0 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68  ex_try().  On th
24df0 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c  ose systems, sql
24e00 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
24e10 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79 73 20   will.** always 
24e20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
24e30 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  SY.  The SQLite 
24e40 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75  core only ever u
24e50 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ses.** sqlite3_m
24e60 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e  utex_try() as an
24e70 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f   optimization so
24e80 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61   this is accepta
24e90 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
24ea0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24eb0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
24ec0 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
24ed0 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
24ee0 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
24ef0 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
24f00 68 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61  hread.  The beha
24f10 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
24f20 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65  ined if the mute
24f30 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  x is not current
24f40 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
24f50 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72  e.** calling thr
24f60 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75  ead or is not cu
24f70 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65  rrently allocate
24f80 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  d.  SQLite will.
24f90 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68  ** never do eith
24fa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
24fb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  so: [sqlite3_mut
24fc0 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b  ex_held()] and [
24fd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
24fe0 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c  theld()]..*/.sql
24ff0 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69  ite3_mutex *sqli
25000 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
25010 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
25020 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71  e3_mutex_free(sq
25030 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
25040 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
25050 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  x_enter(sqlite3_
25060 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
25070 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73  ite3_mutex_try(s
25080 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
25090 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
250a0 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33  ex_leave(sqlite3
250b0 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _mutex*);../*.**
250c0 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
250d0 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f 75   Verifcation Rou
250e0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tines.**.** The 
250f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
25100 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ld() and sqlite3
25110 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
25120 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
25130 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
25140 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28  e inside assert(
25150 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54  ) statements.  T
25160 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a  he SQLite core.*
25170 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65  * never uses the
25180 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65  se routines exce
25190 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73  pt inside an ass
251a0 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63  ert() and applic
251b0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64  ations.** are ad
251c0 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20  vised to follow 
251d0 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20  the lead of the 
251e0 63 6f 72 65 2e 20 20 54 68 65 20 63 6f 72 65 20  core.  The core 
251f0 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
25200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25210 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
25220 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
25230 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
25240 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
25250 20 66 6c 61 67 2e 20 20 45 78 74 65 72 6e 61 6c   flag.  External
25260 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
25270 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e  ations.** are on
25280 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ly required to p
25290 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75  rovide these rou
252a0 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f  tines if SQLITE_
252b0 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69  DEBUG is.** defi
252c0 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55  ned and if NDEBU
252d0 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64  G is not defined
252e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
252f0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65  utines should re
25300 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
25310 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20   mutex in their 
25320 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68  argument.** is h
25330 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c  eld or not held,
25340 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62   respectively, b
25350 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  y the calling th
25360 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  read..**.** The 
25370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
25380 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
25390 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
253a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
253b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
253c0 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20  tually work..** 
253d0 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  If the implement
253e0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70  ation does not p
253f0 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a  rovide working.*
25400 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  * versions of th
25410 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74  ese routines, it
25420 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74   should at least
25430 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 0a 2a   provide stubs.*
25440 2a 20 74 68 61 74 20 61 6c 77 61 79 73 20 72 65  * that always re
25450 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61  turn true so tha
25460 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67  t one does not g
25470 65 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61  et spurious.** a
25480 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65  ssertion failure
25490 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
254a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
254b0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
254c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
254d0 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
254e0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
254f0 74 75 72 6e 20 31 2e 20 20 54 68 69 73 20 73 65  turn 1.  This se
25500 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75  ems counter-intu
25510 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63  itive since.** c
25520 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78  learly the mutex
25530 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20   cannot be held 
25540 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  if it does not e
25550 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a  xist.  But the.*
25560 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65  * the reason the
25570 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20   mutex does not 
25580 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65  exist is because
25590 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f   the build is no
255a0 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78  t.** using mutex
255b0 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e  es.  And we do n
255c0 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65  ot want the asse
255d0 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rt() containing 
255e0 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  the.** call to s
255f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25600 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20  d() to fail, so 
25610 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72  a non-zero retur
25620 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72  n is.** the appr
25630 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f  opriate thing to
25640 20 64 6f 2e 20 20 54 68 65 20 73 71 6c 69 74 65   do.  The sqlite
25650 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
25660 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ) .** interface 
25670 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
25680 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
25690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
256a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
256b0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
256c0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
256d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
256e0 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
256f0 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
25700 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70  I3REF: Mutex Typ
25710 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
25720 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
25730 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  c()] interface t
25740 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
25750 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20  gument.** which 
25760 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
25770 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
25780 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
25790 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
257a0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
257b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
257c0 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  EX_RECURSIVE    
257d0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
257e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
257f0 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64  C_MASTER    2.#d
25800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25810 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20  EX_STATIC_MEM   
25820 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65      3  /* sqlite
25830 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64  3_malloc() */.#d
25840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
25850 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20  EX_STATIC_MEM2  
25860 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
25870 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
25880 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
25890 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
258a0 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f  C_PRNG      5  /
258b0 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  * sqlite3_random
258c0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
258d0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
258e0 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f  C_LRU       6  /
258f0 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
25900 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
25910 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f  EF: Low-Level Co
25920 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73  ntrol Of Databas
25930 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 54 68  e Files.**.** Th
25940 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
25950 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
25960 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
25970 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
25980 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
25990 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
259a0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
259b0 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
259c0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
259d0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
259e0 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
259f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
25a00 75 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 6e  ument.  The.** n
25a10 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
25a20 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ase is the name 
25a30 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20  assigned to the 
25a40 64 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a  database by the.
25a50 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67  ** <a href="lang
25a60 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54  _attach.html">AT
25a70 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d  TACH</a> SQL com
25a80 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64  mand that opened
25a90 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
25aa0 2e 20 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68  .  To control th
25ab0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
25ac0 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61  file, use the na
25ad0 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20  me "main".** or 
25ae0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
25af0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
25b00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
25b10 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
25b20 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64  .** are passed d
25b30 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20  irectly through 
25b40 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  to the second an
25b50 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  d third paramete
25b60 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69  rs of.** the xFi
25b70 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
25b80 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
25b90 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65  lue of the xFile
25ba0 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f  Control.** metho
25bb0 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65  d becomes the re
25bc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
25bd0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
25be0 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * If the second 
25bf0 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
25c00 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
25c10 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
25c20 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
25c30 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
25c40 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
25c50 65 74 75 72 6e 65 64 2e 20 20 54 68 69 73 20 65  eturned.  This e
25c60 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
25c70 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61  not remembered a
25c80 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72  nd will not be r
25c90 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69  ecalled by [sqli
25ca0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a  te3_errcode()].*
25cb0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  * or [sqlite3_er
25cc0 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20 75 6e  rmsg()].  The un
25cd0 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
25ce0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
25cf0 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
25d00 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
25d10 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79   There is no way
25d20 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20   to distinguish 
25d30 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e  between.** an in
25d40 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20  correct zDbName 
25d50 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52  and an SQLITE_ER
25d60 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20  ROR return from 
25d70 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a  the underlying.*
25d80 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  * xFileControl m
25d90 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ethod..**.** See
25da0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46   also: [SQLITE_F
25db0 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a  CNTL_LOCKSTATE].
25dc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
25dd0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69  ile_control(sqli
25de0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
25df0 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f   *zDbName, int o
25e00 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  p, void*);../*.*
25e10 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20  * Undo the hack 
25e20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c  that converts fl
25e30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70  oating point typ
25e40 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f  es to integer fo
25e50 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70  r.** builds on p
25e60 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75  rocessors withou
25e70 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  t floating point
25e80 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66   support..*/.#if
25e90 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
25ea0 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
25eb0 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65   undef double.#e
25ec0 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63  ndif..#ifdef __c
25ed0 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45  plusplus.}  /* E
25ee0 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72  nd of the 'exter
25ef0 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a  n "C"' block */.
25f00 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a        #endif.#endif.