/ Hex Artifact Content
Login

Artifact b4cca54d8c3aa61c033dcb0d48f11ebcdb354627:


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 35 31 20 32 30 30 37 2f  in,v 1.251 2007/
05f0: 30 38 2f 33 30 20 32 30 3a 30 39 3a 34 38 20 64  08/30 20:09:48 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 0a 2a  ersion Numbers.*
0840: 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 69 6f 6e  *.** The version
0850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
0860: 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74 61 69  ibrary is contai
0870: 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  ned in the sqlit
0880: 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72 20 66  e3.h.** header f
0890: 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69 6e 65  ile in a #define
08a0: 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 56 45   named SQLITE_VE
08b0: 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49  RSION.  The SQLI
08c0: 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61  TE_VERSION.** ma
08d0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
08e0: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
08f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72  t..**.** The for
0900: 6d 61 74 20 6f 66 20 74 68 65 20 76 65 72 73 69  mat of the versi
0910: 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e  on string is "X.
0920: 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58  Y.Z", where.** X
0930: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20  rsion number, Y 
0950: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0960: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0970: 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65  Z.** is the rele
0980: 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ase number.  The
0990: 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 62 65 20   X.Y.Z might be 
09a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 61 6c 70  followed by "alp
09b0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a  ha" or "beta"..*
09c0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22 33  * For example "3
09d0: 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a  .1.1beta"..**.**
09e0: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20   The X value is 
09f0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0a00: 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75 65  te.  The X value
0a10: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0a20: 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  en.** backwards 
0a30: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0a40: 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69   broken and we i
0a50: 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62  ntend to never b
0a60: 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64  reak.** backward
0a70: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0a80: 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f 6e    The Y value on
0a90: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
0aa0: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a  ** there are maj
0ab0: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e  or feature enhan
0ac0: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  cements that are
0ad0: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74   forwards compat
0ae0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ible.** but not 
0af0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0b00: 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61 6c  ible.  The Z val
0b10: 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  ue is incremente
0b20: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0b30: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0b40: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0b50: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b60: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
0b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b80: 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ER is an integer
0b90: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0ba0: 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 30 20 2b  .** (X*1000000 +
0bb0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f   Y*1000 + Z). Fo
0bc0: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76  r example, for v
0bd0: 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74  ersion "3.1.1bet
0be0: 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56  a", .** SQLITE_V
0bf0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73  ERSION_NUMBER is
0c00: 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31 2e   set to 3001001.
0c10: 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74 68   To detect if th
0c20: 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a  ey are using .**
0c30: 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f   version 3.1.1 o
0c40: 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f 6d  r greater at com
0c50: 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67 72  pile time, progr
0c60: 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65 20  ams may use the 
0c70: 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45  test .** (SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e  _VERSION_NUMBER>
0c90: 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a  =3001001)..**.**
0ca0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
0cb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0cc0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c  ] and [sqlite3_l
0cd0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0ce0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
0cf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
0d00: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d30: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d40: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0d50: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0d60: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0d70: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  bers.**.** These
0d80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
0d90: 20 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65   values equivale
0da0: 6e 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72  nt to the header
0db0: 20 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53   constants.** [S
0dc0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61  QLITE_VERSION] a
0dd0: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  nd [SQLITE_VERSI
0de0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65  ON_NUMBER].  The
0df0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
0e00: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
0e10: 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  ines should only
0e20: 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72   be different fr
0e30: 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61  om the header va
0e40: 6c 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63  lues.** if you c
0e50: 6f 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67  ompile your prog
0e60: 72 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c  ram using an sql
0e70: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72  ite3.h header fr
0e80: 6f 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  om a.** differen
0e90: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  t version of SQL
0ea0: 69 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72  ite that the ver
0eb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72  sion of the libr
0ec0: 61 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20  ary you.** link 
0ed0: 61 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  against..**.** T
0ee0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
0ef0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
0f00: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
0f10: 65 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a  e text of the.**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f30: 5d 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73  ] string.  The s
0f40: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0f50: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
0f60: 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72  urns.** a poiner
0f70: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
0f80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0f90: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
0fa0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70  function.** is p
0fb0: 72 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20  rovided for DLL 
0fc0: 75 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e  users who can on
0fd0: 6c 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  ly access functi
0fe0: 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63  ons and not.** c
0ff0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1000: 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  the DLL..*/.SQLI
1010: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
1020: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1030: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1040: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1050: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1060: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1070: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1080: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1090: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
10a0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
10b0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
10c0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10d0: 72 65 74 75 72 6e 73 20 54 52 55 45 20 28 6e 6f  returns TRUE (no
10e0: 6e 7a 65 72 6f 29 20 69 66 20 53 51 4c 69 74 65  nzero) if SQLite
10f0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1100: 74 68 0a 2a 2a 20 61 6c 6c 20 6f 66 20 69 74 73  th.** all of its
1110: 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64   mutexes enabled
1120: 20 61 6e 64 20 69 73 20 74 68 75 73 20 74 68 72   and is thus thr
1130: 65 61 64 73 61 66 65 2e 20 20 49 74 20 72 65 74  eadsafe.  It ret
1140: 75 72 6e 73 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  urns.** zero if 
1150: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 62  the particular b
1160: 75 69 6c 64 20 69 73 20 66 6f 72 20 73 69 6e 67  uild is for sing
1170: 6c 65 2d 74 68 72 65 61 64 65 64 20 6f 70 65 72  le-threaded oper
1180: 61 74 69 6f 6e 0a 2a 2a 20 6f 6e 6c 79 2e 0a 2a  ation.** only..*
1190: 2a 0a 2a 2a 20 52 65 61 6c 6c 79 20 61 6c 6c 20  *.** Really all 
11a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 64 6f 65  this routine doe
11b0: 73 20 69 73 20 72 65 74 75 72 6e 20 74 72 75 65  s is return true
11c0: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
11d0: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
11e0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  the -DSQLITE_THR
11f0: 45 41 44 53 41 46 45 3d 31 20 6f 70 74 69 6f 6e  EADSAFE=1 option
1200: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 0a 2a 2a   and false if.**
1210: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 2d   compiled with -
1220: 44 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  DSQLITE_THREADSA
1230: 46 45 3d 30 2e 20 20 49 66 20 53 51 4c 69 74 65  FE=0.  If SQLite
1240: 20 75 73 65 73 20 61 6e 0a 2a 2a 20 61 70 70 6c   uses an.** appl
1250: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1260: 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 2c  mutex subsystem,
1270: 20 6d 61 6c 6c 6f 63 20 73 75 62 73 79 73 74 65   malloc subsyste
1280: 6d 2c 20 63 6f 6c 6c 61 74 69 6e 67 0a 2a 2a 20  m, collating.** 
1290: 73 65 71 75 65 6e 63 65 2c 20 56 46 53 2c 20 53  sequence, VFS, S
12a0: 51 4c 20 66 75 6e 63 74 69 6f 6e 2c 20 70 72 6f  QL function, pro
12b0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 2c 20  gress callback, 
12c0: 63 6f 6d 6d 69 74 20 68 6f 6f 6b 2c 0a 2a 2a 20  commit hook,.** 
12d0: 65 78 74 65 6e 73 69 6f 6e 2c 20 6f 72 20 6f 74  extension, or ot
12e0: 68 65 72 20 61 63 63 65 73 73 6f 72 69 65 73 20  her accessories 
12f0: 61 6e 64 20 74 68 65 73 65 20 61 64 64 2d 6f 6e  and these add-on
1300: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 74 68 72  s are not.** thr
1310: 65 61 64 73 61 66 65 2c 20 74 68 65 6e 20 63 6c  eadsafe, then cl
1320: 65 61 72 6c 79 20 74 68 65 20 63 6f 6d 62 69 6e  early the combin
1330: 61 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74 20 62  ation will not b
1340: 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a 20  e threadsafe.** 
1350: 65 69 74 68 65 72 2e 20 20 48 65 6e 63 65 2c 20  either.  Hence, 
1360: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6e 65 76  this routine nev
1370: 65 72 20 72 65 70 6f 72 74 73 20 74 68 61 74 20  er reports that 
1380: 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
1390: 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  s guaranteed to 
13a0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2c 20 6f  be threadsafe, o
13b0: 6e 6c 79 20 77 68 65 6e 20 69 74 20 69 73 20 67  nly when it is g
13c0: 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a  uaranteed not.**
13d0: 20 74 6f 20 62 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   to be..**.** Th
13e0: 69 73 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d  is is an experim
13f0: 65 6e 74 61 6c 20 41 50 49 20 61 6e 64 20 6d 61  ental API and ma
1400: 79 20 67 6f 20 61 77 61 79 20 6f 72 20 63 68 61  y go away or cha
1410: 6e 67 65 20 69 6e 20 66 75 74 75 72 65 0a 2a 2a  nge in future.**
1420: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1430: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
1440: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
1450: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1460: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1470: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61   Handle.**.** Ea
1480: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1490: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
14a0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
14b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14c0: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
14d0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
14e0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
14f0: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1500: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1510: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1520: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1530: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1540: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1550: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
1560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1570: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1580: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1590: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
15a0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
15b0: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
15c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
15d0: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
15e0: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
15f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1600: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1610: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1620: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1630: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1640: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
1650: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
1660: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
1670: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1690: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
16a0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
16b0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
16c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d 70 69  **.** Some compi
16d0: 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 70 70  lers do not supp
16e0: 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 6c 6f  ort the "long lo
16f0: 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 20 53  ng" datatype.  S
1700: 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 6f 20  o we have.** to 
1710: 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 65 63  do compiler-spec
1720: 69 66 69 63 20 74 79 70 65 64 65 66 73 20 66 6f  ific typedefs fo
1730: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1740: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1750: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d 61 6e  egers..**.** Man
1760: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
1770: 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 71  ce functions req
1780: 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 69 6e  uire a 64-bit in
1790: 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 73 2e  teger arguments.
17a0: 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 72 66  .** Those interf
17b0: 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 72 65  aces are declare
17c0: 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 79 70  d using this typ
17d0: 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  edef..*/.#ifdef 
17e0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
17f0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
1800: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
1810: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1820: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
1830: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1840: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1850: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
1860: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
1870: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
1880: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
1890: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
18a0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
18b0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
18c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
18d0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
18e0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
18f0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1900: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
1910: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
1920: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
1930: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
1940: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
1950: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
1960: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1970: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
1980: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
1990: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
19a0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
19b0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
19c0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
19d0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
19e0: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65  g-point.*/.#ifde
19f0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
1a00: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
1a10: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
1a20: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
1a30: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1a40: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
1a50: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1a60: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73  .**.** Call this
1a70: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
1a80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
1a90: 72 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73  ructure that was
1aa0: 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72   previously.** r
1ab0: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
1ac0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1ad0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ae0: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1af0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
1b00: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
1b10: 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ng database will
1b20: 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a   by.** closed..*
1b30: 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61  *.** All SQL sta
1b40: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64  tements prepared
1b50: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b60: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1b80: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73  pare16_v2()] mus
1b90: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75  t be destroyed u
1ba0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1bb0: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66  nalize()].** bef
1bc0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ore this routine
1bd0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65   is called. Othe
1be0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55  rwise, SQLITE_BU
1bf0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  SY is returned a
1c00: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
1c10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65  se connection re
1c20: 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  mains open..**.*
1c30: 2a 20 50 61 73 73 69 6e 67 20 74 68 69 73 20 72  * Passing this r
1c40: 6f 75 74 69 6e 65 20 61 20 64 61 74 61 62 61 73  outine a databas
1c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c60: 74 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  t has already be
1c70: 65 6e 0a 2a 2a 20 63 6c 6f 73 65 64 20 72 65 73  en.** closed res
1c80: 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
1c90: 64 20 62 65 68 61 76 69 6f 72 2e 20 20 49 66 20  d behavior.  If 
1ca0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1cb0: 20 74 68 61 74 0a 2a 2a 20 72 65 66 65 72 65 6e   that.** referen
1cc0: 63 65 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  ce the same data
1cd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ce0: 61 72 65 20 70 65 6e 64 69 6e 67 20 28 65 69 74  are pending (eit
1cf0: 68 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 73 61  her in the.** sa
1d00: 6d 65 20 74 68 72 65 61 64 20 6f 72 20 69 6e 20  me thread or in 
1d10: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
1d20: 73 29 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  s) when this rou
1d30: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 0a  tine is called,.
1d40: 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d50: 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d60: 64 20 61 6e 64 20 69 73 20 61 6c 6d 6f 73 74 20  d and is almost 
1d70: 63 65 72 74 61 69 6e 6c 79 20 75 6e 64 65 73 69  certainly undesi
1d80: 72 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  rable..*/.int sq
1d90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
1da0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
1db0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
1dc0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
1dd0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
1de0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
1df0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
1e00: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
1e10: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
1e20: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
1e30: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
1e40: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
1e50: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
1e60: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
1e70: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
1e80: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
1e90: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
1ea0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
1eb0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ec0: 20 69 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61   is used to do a
1ed0: 20 6f 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61   one-time evalua
1ee0: 74 61 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a  tation of zero.*
1ef0: 2a 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74  * or more SQL st
1f00: 61 74 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38  atements.  UTF-8
1f10: 20 74 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c   text of the SQL
1f20: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a   statements to.*
1f30: 2a 20 62 65 20 65 76 61 6c 75 74 65 64 20 69 73  * be evaluted is
1f40: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
1f50: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f60: 65 72 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  er.  The stateme
1f70: 6e 74 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61  nts.** are prepa
1f80: 72 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75  red one by one u
1f90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1fa0: 65 70 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61  epare()], evalua
1fb0: 74 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ted.** using [sq
1fc0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74  lite3_step()], t
1fd0: 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73  hen destroyed us
1fe0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1ff0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
2000: 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  If one or more o
2010: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2020: 65 6e 74 73 20 61 72 65 20 71 75 65 72 69 65 73  ents are queries
2030: 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61  , then.** the ca
2040: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2050: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2060: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2070: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  s.** invoked onc
2080: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2090: 66 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  f the query resu
20a0: 6c 74 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61  lt.  This callba
20b0: 63 6b 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72  ck.** should nor
20c0: 6d 61 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20  mally return 0. 
20d0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
20e0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
20f0: 65 72 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65  ero.** value the
2100: 6e 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61  n the query is a
2110: 62 6f 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73  borted, all subs
2120: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
2130: 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69  ments.** are ski
2140: 70 70 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c  pped and the sql
2150: 69 74 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63  ite3_exec() func
2160: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
2170: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a   SQLITE_ABORT..*
2180: 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  *.** The 4th par
2190: 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73 20 69  ameter to this i
21a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 6e 20 61  nterface is an a
21b0: 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
21c0: 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 61 73 73   that is.** pass
21d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
21e0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
21f0: 69 6f 6e 20 61 73 20 69 74 73 20 66 69 72 73 74  ion as its first
2200: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2210: 2a 20 54 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * The 2nd parame
2220: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2230: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
2240: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2250: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2260: 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54  query result.  T
2270: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2280: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2290: 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72 61 79 20  .** is an array 
22a0: 6f 66 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  of strings holdi
22b0: 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20 66 6f  ng the values fo
22c0: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a  r each column.**
22d0: 20 61 73 20 65 78 74 72 61 63 74 65 64 20 75 73   as extracted us
22e0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
22f0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20  umn_text()]..** 
2300: 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
2310: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
2320: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
2330: 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61   strings.** obta
2340: 69 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ined using [sqli
2350: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2360: 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a  )] and holding.*
2370: 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 65  * the names of e
2380: 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ach column..**.*
2390: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
23a0: 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e  unction may be N
23b0: 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20 71 75  ULL, even for qu
23c0: 65 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a  eries.  A NULL.*
23d0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  * callback is no
23e0: 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 74 20  t an error.  It 
23f0: 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61 74 20  just means that 
2400: 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77  no callback.** w
2410: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a  ill be invoked..
2420: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  **.** If an erro
2430: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70  r occurs while p
2440: 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61  arsing or evalua
2450: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 28 62 75  ting the SQL (bu
2460: 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65  t.** not while e
2470: 78 65 63 75 74 69 6e 67 20 74 68 65 20 63 61 6c  xecuting the cal
2480: 6c 62 61 63 6b 29 20 74 68 65 6e 20 61 6e 20 61  lback) then an a
2490: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
24a0: 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73 20 77  .** message is w
24b0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
24c0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
24d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
24e0: 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d  ()] and.** *errm
24f0: 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  sg is made to po
2500: 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73  int to that mess
2510: 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  age.  The callin
2520: 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73  g function.** is
2530: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
2540: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
2550: 6f 72 79 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ory that holds t
2560: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2570: 61 67 65 2e 20 20 20 55 73 65 20 5b 73 71 6c 69  age.   Use [sqli
2580: 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
2590: 74 68 69 73 2e 20 20 49 66 20 65 72 72 6d 73 67  this.  If errmsg
25a0: 3d 3d 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  ==NULL,.** then 
25b0: 6e 6f 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  no error message
25c0: 20 69 73 20 65 76 65 72 20 77 72 69 74 74 65 6e   is ever written
25d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
25e0: 72 6e 20 76 61 6c 75 65 20 69 73 20 69 73 20 53  rn value is is S
25f0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72  QLITE_OK if ther
2600: 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20  e are no errors 
2610: 61 6e 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65  and.** some othe
2620: 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  r [SQLITE_OK | r
2630: 65 74 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74  eturn code] if t
2640: 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2650: 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69  .  .** The parti
2660: 63 75 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c  cular return val
2670: 75 65 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68  ue depends on th
2680: 65 20 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e  e type of error.
2690: 20 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69   .**.*/.int sqli
26a0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
26b0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
26c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26d0: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
26e0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
26f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
2700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2710: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
2720: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64  L to be evaluted
2730: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
2740: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
2750: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
2760: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
2770: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
2780: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
2790: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27a0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
27b0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
27c0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
27d0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
27e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27f0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
2800: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
2810: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2820: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
2830: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2840: 49 54 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e  ITE_OK.**.** Man
2850: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
2860: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
2870: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
2880: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
2890: 6f 77 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20  own.** above in 
28a0: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74  order to indicat
28b0: 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  es success or fa
28c0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ilure..**.** The
28d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62   result codes ab
28e0: 6f 76 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ove are the only
28f0: 20 6f 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62   ones returned b
2900: 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a  y SQLite in its.
2910: 2a 2a 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ** default confi
2920: 67 75 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76  guration.  Howev
2930: 65 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  er, the [sqlite3
2940: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
2950: 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49  _codes()].** API
2960: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2970: 73 65 74 20 61 20 64 61 74 61 62 61 73 65 20 63  set a database c
2980: 6f 6e 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74  onnectoin to ret
2990: 75 72 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  urn more detaile
29a0: 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65  d.** result code
29b0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
29c0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
29d0: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
29e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
29f0: 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  *.*/.#define SQL
2a00: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
2a10: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
2a20: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
2a30: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
2a40: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
2a50: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
2a60: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
2a70: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
2a80: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
2a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2aa0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
2ab0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74  /* NOT USED. Int
2ac0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
2ad0: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
2ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
2af0: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
2b00: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
2b10: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
2b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
2b30: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
2b40: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
2b50: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
2b60: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
2b70: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
2b80: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
2b90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
2ba0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
2bb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
2bc0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
2bd0: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
2be0: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
2bf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c00: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
2c10: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
2c20: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
2c30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
2c40: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
2c50: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
2c60: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
2c70: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
2c80: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
2c90: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
2ca0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
2cb0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
2cc0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
2cd0: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
2ce0: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
2cf0: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
2d00: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
2d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d20: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
2d30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
2d40: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
2d50: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
2d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
2d70: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
2d80: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
2d90: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
2da0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
2db0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
2dc0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
2dd0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
2de0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
2df0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
2e00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
2e10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
2e20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
2e30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
2e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
2e50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
2e60: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
2e70: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
2e80: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
2e90: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
2ea0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
2eb0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
2ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ed0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
2ee0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
2ef0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
2f00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2f10: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
2f20: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
2f30: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
2f40: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
2f50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
2f60: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
2f70: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74  bort due to cont
2f80: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
2f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fa0: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
2fb0: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
2fc0: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
2fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
2fe0: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
2ff0: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
3000: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
3010: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
3020: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
3030: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
3040: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
3050: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
3060: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
3070: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
3080: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
3090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
30a0: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
30b0: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
30c0: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
30d0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
30e0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
30f0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
3100: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3110: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
3120: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
3130: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
3140: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
3150: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
3160: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
3170: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
3180: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
3190: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
31a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
31b0: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
31c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31d0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
31e0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
31f0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
3200: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
3210: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
3220: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
3230: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
3240: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
3250: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
3260: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
3270: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
3280: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
3290: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
32a0: 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ** result codes 
32b0: 64 65 73 63 72 69 62 65 64 20 61 74 20 72 65 73  described at res
32c0: 75 6c 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65  ult-codes.  Howe
32d0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
32e0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a  has shown that.*
32f0: 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20  * many of these 
3300: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
3310: 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69   too course-grai
3320: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
3330: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
3340: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
3350: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
3360: 61 73 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c  as users might l
3370: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
3380: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
3390: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
33a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
33b0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
33c0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
33d0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
33e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
33f0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
3400: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
3410: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
3420: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
3430: 20 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72    The extended r
3440: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
3450: 65 6e 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61  enabled (or disa
3460: 62 6c 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61  bled) for .** ea
3470: 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ch database.** c
3480: 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20  onnection using 
3490: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  the [sqlite3_ext
34a0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
34b0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a  es()] API..** .*
34c0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
34d0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
34e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
34f0: 65 20 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a  e listed above..
3500: 2a 2a 20 57 65 20 65 78 70 65 63 74 20 74 68 65  ** We expect the
3510: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
3520: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
3530: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
3540: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
3550: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
3560: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
3570: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
3580: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
3590: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
35a0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
35b0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
35c0: 2a 20 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c  * .** The symbol
35d0: 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65  ic name for an e
35e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
35f0: 6f 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61  ode always conta
3600: 69 6e 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a  ins a related.**
3610: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
3620: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
3630: 2e 20 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  .  Primary resul
3640: 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20  t codes contain 
3650: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20  a single.** "_" 
3660: 63 68 61 72 61 63 74 65 72 2e 20 20 45 78 74 65  character.  Exte
3670: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3680: 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  s contain two or
3690: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
36a0: 74 65 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d  ters..** The num
36b0: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e  eric value of an
36c0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
36d0: 20 63 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e   code can be con
36e0: 76 65 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a  verted to its.**
36f0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70   corresponding p
3700: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f  rimary result co
3710: 64 65 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66  de by masking of
3720: 66 20 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79  f the lower 8 by
3730: 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  tes..**.** The S
3740: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
3750: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
3760: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
3770: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
3780: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
3790: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
37a0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
37b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
37c0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
37d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
37e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
37f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3800: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
3810: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
3820: 52 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51  RITE         (SQ
3830: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
3840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3850: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
3860: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
3870: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
3880: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3890: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
38a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
38b0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
38c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
38d0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53  TRUNCATE      (S
38e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
38f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3900: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
3910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
3920: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
3930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3940: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
3950: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3960: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
3970: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3980: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28  _RDLOCK        (
3990: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
39a0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
39b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
39c0: 54 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  TE        (SQLIT
39d0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
39e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
39f0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
3a00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3a10: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a  ERR | (11<<8))..
3a20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3a30: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
3a40: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
3a50: 2a 0a 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e  *.** Combination
3a60: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
3a70: 67 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  g bit values are
3a80: 20 75 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20   used as the.** 
3a90: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
3aa0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
3ab0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
3ac0: 61 63 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f  ace and.** as fo
3ad0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
3ae0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
3af0: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
3b00: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
3b10: 2e 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ..**.*/.#define 
3b20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
3b30: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
3b40: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
3b50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
3b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
3b70: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
3b80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
3b90: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
3ba0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
3bb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
3bc0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
3bd0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
3be0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
3bf0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
3c00: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
3c10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
3c20: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
3c30: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
3c40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
3c50: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
3c60: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
3c70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
3c80: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
3c90: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
3ca0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
3cb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
3cc0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
3cd0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
3ce0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
3cf0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
3d00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
3d10: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
3d20: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
3d30: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
3d40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
3d50: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
3d60: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
3d70: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
3d80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
3d90: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
3da0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
3db0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
3dc0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3dd0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
3de0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
3df0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
3e00: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
3e10: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
3e20: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
3e30: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
3e40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
3e50: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
3e60: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
3e70: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
3e80: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
3e90: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
3ea0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
3eb0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
3ec0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
3ed0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
3ee0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
3ef0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
3f00: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
3f10: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
3f20: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
3f30: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
3f40: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
3f50: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
3f60: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
3f70: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
3f80: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
3f90: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
3fa0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
3fb0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
3fc0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
3fd0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
3fe0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
3ff0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
4000: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
4010: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
4020: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4030: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
4040: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
4050: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
4060: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
4070: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
4080: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
4090: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
40a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
40b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
40c0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
40d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
40e0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
40f0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4110: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
4120: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
4130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4140: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
4150: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
4160: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4170: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
4180: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
4190: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
41a0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
41b0: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
41c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
41d0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
41e0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
41f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4200: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
4210: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
4220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4230: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
4240: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
4250: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4260: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
4270: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
4280: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4290: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
42a0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
42b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
42c0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
42d0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
42e0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  es one of the fo
42f0: 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
4300: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
4310: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
4320: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
4330: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
4340: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
4350: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
4360: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4370: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
43a0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
43b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
43c0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
43d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
43e0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
43f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4400: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
4410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4420: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
4430: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
4440: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
4450: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
4460: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
4470: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
4480: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
4490: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
44a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
44b0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
44c0: 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  bination of the 
44d0: 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
44e0: 72 20 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74  r values as.** t
44f0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
4500: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
4510: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4520: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
4530: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
4540: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
4550: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
4560: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
4570: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
4580: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
4590: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
45a0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20  ot be flushed.  
45b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
45c0: 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a  NORMAL means .**
45d0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
45e0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
45f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  .  The SQLITE_SY
4600: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
4610: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
4620: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
4630: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
4640: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
4650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
4660: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
4670: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
4680: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
4690: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
46c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
46d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
46e0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
46f0: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
4700: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
4710: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
4720: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
4730: 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69  e in the OS.** i
4740: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20  nterface layer. 
4750: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
4760: 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65  nterface impleme
4770: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
4780: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
4790: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
47a0: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
47b0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
47c0: 6f 66 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  of their own use
47d0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
47e0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
47f0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
4800: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4810: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
4820: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
4830: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
4840: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
4850: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
4860: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
4870: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
4880: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
4890: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
48a0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
48b0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
48c0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
48d0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
48e0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
48f0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
4900: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
4910: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
4920: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
4930: 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e 20 66 69  ** Every open fi
4940: 6c 65 20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74  le in the [sqlit
4950: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
4960: 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20 61 20  thod contains a 
4970: 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
4980: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
4990: 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62 6a 65 63   following objec
49a0: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
49b0: 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d  defines the.** m
49c0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
49d0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
49e0: 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73  perations agains
49f0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  t the open file.
4a00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
4a10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
4a20: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
4a30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
4a40: 4d 41 4c 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  MAL or.** SQLITE
4a50: 5f 53 59 4e 43 5f 46 55 4c 4c 2e 20 20 54 68 65  _SYNC_FULL.  The
4a60: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 6d 65   first choice me
4a70: 61 6e 73 20 74 68 61 74 20 64 61 74 61 20 69 73  ans that data is
4a80: 20 6e 6f 74 0a 2a 2a 20 6e 65 63 65 73 73 61 72   not.** necessar
4a90: 69 6c 79 20 73 79 6e 63 65 64 20 74 6f 20 64 69  ily synced to di
4aa0: 73 6b 20 63 6f 6d 70 6c 65 74 65 6c 79 2c 20 6f  sk completely, o
4ab0: 6e 6c 79 20 74 68 61 74 20 61 6c 6c 20 77 72 69  nly that all wri
4ac0: 74 65 73 20 74 68 61 74 0a 2a 2a 20 6f 63 63 75  tes that.** occu
4ad0: 72 20 62 65 66 6f 72 65 20 74 68 65 20 73 79 6e  r before the syn
4ae0: 63 20 63 6f 6d 70 6c 65 74 65 20 62 65 66 6f 72  c complete befor
4af0: 65 20 61 6e 79 20 77 72 69 74 65 73 20 74 68 61  e any writes tha
4b00: 74 20 6f 63 63 75 72 20 61 66 74 65 72 20 74 68  t occur after th
4b10: 65 0a 2a 2a 20 73 79 6e 63 2e 20 20 54 68 65 20  e.** sync.  The 
4b20: 73 65 63 6f 6e 64 20 66 6c 61 67 20 69 73 20 74  second flag is t
4b30: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
4b40: 29 2e 20 20 54 68 65 20 74 68 69 72 64 20 66 6c  ).  The third fl
4b50: 61 67 20 69 73 20 61 0a 2a 2a 20 4f 53 2d 58 20  ag is a.** OS-X 
4b60: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
4b70: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
4b80: 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62  _DATA flag may b
4b90: 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20  e ORed in to.** 
4ba0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
4bb0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
4bc0: 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20  he file and not 
4bd0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
4be0: 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e  to be.** synced.
4bf0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65  .** .** The inte
4c00: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
4c10: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
4c20: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
4c30: 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  * SQLITE_LOCK_NO
4c40: 4e 45 2c 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  NE, SQLITE_LOCK_
4c50: 52 45 41 44 2c 20 53 51 4c 49 54 45 5f 4c 4f 43  READ, SQLITE_LOC
4c60: 4b 5f 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 53  K_RESERVED,.** S
4c70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
4c80: 4e 47 2c 20 6f 72 20 53 51 4c 49 54 45 5f 4c 4f  NG, or SQLITE_LO
4c90: 43 4b 5f 45 58 43 4c 55 53 49 56 45 2e 20 20 78  CK_EXCLUSIVE.  x
4ca0: 4c 6f 63 6b 28 29 0a 2a 2a 20 69 6e 63 72 65 61  Lock().** increa
4cb0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
4cc0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
4cd0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  s the lock.  .**
4ce0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
4cf0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
4d00: 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65   looks.** to see
4d10: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
4d20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74   connection, eit
4d30: 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70  her in this.** p
4d40: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
4d50: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
4d60: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52   is holding an R
4d70: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
4d80: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
4d90: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
4da0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
4db0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
4dc0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
4dd0: 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a  d false if not..
4de0: 2a 2a 20 0a 2a 2a 20 78 42 72 65 61 6b 4c 6f 63  ** .** xBreakLoc
4df0: 6b 28 29 20 61 74 74 65 6d 70 74 73 20 74 6f 20  k() attempts to 
4e00: 62 72 65 61 6b 20 61 20 6c 6f 63 6b 20 68 65 6c  break a lock hel
4e10: 64 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f  d by another pro
4e20: 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 63 61  cess..** This ca
4e30: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 6d  n be used to rem
4e40: 6f 76 65 20 61 20 73 74 61 6c 65 20 64 6f 74 2d  ove a stale dot-
4e50: 66 69 6c 65 20 6c 6f 63 6b 2c 20 66 6f 72 20 65  file lock, for e
4e60: 78 61 6d 70 6c 65 2e 0a 2a 2a 20 49 74 20 72 65  xample..** It re
4e70: 74 75 72 6e 73 20 30 20 6f 6e 20 73 75 63 63 65  turns 0 on succe
4e80: 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a 65 72 6f 20  ss and non-zero 
4e90: 66 6f 72 20 61 20 66 61 69 6c 75 72 65 2e 0a 2a  for a failure..*
4ea0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
4eb0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
4ec0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
4ed0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
4ee0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
4ef0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
4f00: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
4f10: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
4f20: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
4f30: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
4f40: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
4f50: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
4f60: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
4f70: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
4f80: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
4f90: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
4fa0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
4fb0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
4fc0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
4fd0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
4fe0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
4ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5000: 4d 49 43 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  MIC.** <li> SQLI
5010: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5020: 31 32 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  12.** <li> SQLIT
5030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
5040: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f  .** <li> SQLITE_
5050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 0a 2a  IOCAP_ATOMIC2K.*
5060: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f  * <li> SQLITE_IO
5070: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 0a 2a 2a 20  CAP_ATOMIC4K.** 
5080: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
5090: 50 5f 41 54 4f 4d 49 43 38 4b 0a 2a 2a 20 3c 6c  P_ATOMIC8K.** <l
50a0: 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  i> SQLITE_IOCAP_
50b0: 41 54 4f 4d 49 43 31 36 4b 0a 2a 2a 20 3c 6c 69  ATOMIC16K.** <li
50c0: 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  > SQLITE_IOCAP_A
50d0: 54 4f 4d 49 43 33 32 4b 0a 2a 2a 20 3c 6c 69 3e  TOMIC32K.** <li>
50e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
50f0: 4f 4d 49 43 36 34 4b 0a 2a 2a 20 3c 6c 69 3e 20  OMIC64K.** <li> 
5100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5110: 45 5f 41 50 50 45 4e 44 0a 2a 2a 20 3c 6c 69 3e  E_APPEND.** <li>
5120: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5130: 51 55 45 4e 54 49 41 4c 0a 2a 2a 20 3c 2f 75 6c  QUENTIAL.** </ul
5140: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
5150: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5160: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5170: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
5180: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5190: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
51a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
51b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
51c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
51d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
51e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
51f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5200: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
5210: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
5220: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
5230: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
5240: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5260: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
5270: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
5280: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5290: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
52a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
52b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
52c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
52d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
52e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
52f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5300: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5310: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
5320: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5330: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
5340: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
5350: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
5360: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
5370: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
5380: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5390: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
53a0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
53b0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
53c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
53d0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
53e0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
53f0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
5400: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
5410: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
5420: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
5430: 74 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  t, sqlite_int64 
5440: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
5450: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
5460: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
5470: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
5480: 6c 69 74 65 5f 69 6e 74 36 34 20 69 4f 66 73 74  lite_int64 iOfst
5490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
54a0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
54b0: 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36  le*, sqlite_int6
54c0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
54d0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
54e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
54f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
5500: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
5510: 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36  le*, sqlite_int6
5520: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
5530: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
5540: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
5550: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
5560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
5570: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
5580: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
5590: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
55a0: 0a 20 20 69 6e 74 20 28 2a 78 42 72 65 61 6b 4c  .  int (*xBreakL
55b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
55c0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  e*);.  int (*xLo
55d0: 63 6b 53 74 61 74 65 29 28 73 71 6c 69 74 65 33  ckState)(sqlite3
55e0: 5f 66 69 6c 65 20 2a 29 3b 0a 20 20 69 6e 74 20  _file *);.  int 
55f0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
5600: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
5610: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
5620: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
5630: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
5640: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
5650: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
5660: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
5670: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
5680: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
5690: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
56a0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
56b0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
56c0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
56d0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
56e0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
56f0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
5700: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
5710: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
5720: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
5730: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
5740: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
5750: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
5760: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
5770: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
5780: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
5790: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
57a0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
57b0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
57c0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
57d0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
57e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
57f0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
5800: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
5810: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
5820: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
5830: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
5840: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
5850: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
5860: 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51  etween the.** SQ
5870: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
5880: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
5890: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
58a0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
58b0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
58c0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
58d0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
58e0: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54  system"..**.** T
58f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
5900: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
5910: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
5920: 65 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a  er for future.**
5930: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
5940: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
5950: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
5960: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
5970: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
5980: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
5990: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a  e is increased..
59a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
59b0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
59c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
59d0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
59e0: 69 6c 65 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ile.** structure
59f0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
5a00: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
5a10: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
5a20: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
5a30: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
5a40: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
5a50: 72 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20  red vfs modules 
5a60: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
5a70: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
5a80: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
5a90: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
5aa0: 73 71 6c 69 74 65 33 5f 72 65 67 69 73 74 65 72  sqlite3_register
5ab0: 5f 76 66 73 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  _vfs()].** and [
5ac0: 73 71 6c 69 74 65 33 5f 75 6e 72 65 67 69 73 74  sqlite3_unregist
5ad0: 65 72 5f 76 66 73 28 29 5d 20 69 6e 74 65 72 66  er_vfs()] interf
5ae0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
5af0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
5b00: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
5b10: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  The [sqlite3_fin
5b20: 64 5f 76 66 73 28 29 5d 20 69 6e 74 65 72 66 61  d_vfs()] interfa
5b30: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
5b40: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
5b50: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
5b60: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
5b70: 73 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  s in the sqlite3
5b80: 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75  _vfs .** structu
5b90: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
5ba0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
5bb0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
5bc0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
5bd0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
5be0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
5bf0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
5c00: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
5c10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
5c20: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
5c30: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
5c40: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
5c50: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
5c60: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
5c70: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
5c80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
5c90: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
5ca0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
5cb0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
5cc0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
5cd0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
5ce0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
5cf0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
5d00: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
5d10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
5d20: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
5d30: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
5d40: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
5d50: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
5d60: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
5d70: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
5d80: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
5d90: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
5da0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
5db0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74  ** called.  So t
5dc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
5dd0: 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f  ] can store a po
5de0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
5df0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
5e00: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
5e10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
5e20: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
5e30: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5e40: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
5e50: 28 29 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  () is a copy of 
5e60: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
5e70: 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
5e80: 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 49 66 20  _open_v2().  If 
5e90: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
5ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
5eb0: 28 29 0a 2a 2a 20 69 73 20 75 73 65 64 2c 20 74  ().** is used, t
5ec0: 68 65 6e 20 66 6c 61 67 73 20 69 73 20 53 51 4c  hen flags is SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5ee0: 54 45 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  TE | SQLITE_OPEN
5ef0: 5f 43 52 45 41 54 45 2e 0a 2a 2a 20 49 66 20 78  _CREATE..** If x
5f00: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
5f10: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
5f20: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
5f30: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
5f40: 75 64 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ude SQLITE_OPEN_
5f50: 52 45 41 44 4f 4e 4c 59 2e 20 20 4f 74 68 65 72  READONLY.  Other
5f60: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
5f70: 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65  ags may be.** se
5f80: 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65  t..** .** SQLite
5f90: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
5fa0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
5fb0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
5fc0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
5fd0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
5fe0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
5ff0: 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  opened:.** .** <
6000: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
6010: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6020: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
6030: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
6040: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
6050: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
6060: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
6070: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
6080: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
6090: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
60a0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
60b0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
60c0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
60d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
60e0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
60f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
6100: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
6110: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
6120: 20 63 68 61 6e 67 65 73 20 74 68 65 20 77 61 79   changes the way
6130: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
6140: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
6150: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
6160: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
6170: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
6180: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
6190: 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74   rollback, might
61a0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
61b0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
61c0: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
61d0: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
61e0: 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f  rnal are.** also
61f0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61   a no-op.  Any a
6200: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
6210: 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72  he journal retur
6220: 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a  n SQLITE_IOERR..
6230: 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  ** Or the implem
6240: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
6250: 65 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64  ecognize the a d
6260: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
6270: 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61  l.** be doing pa
6280: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
6290: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
62a0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f  es in a random o
62b0: 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20  rder.** and set 
62c0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
62d0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
62e0: 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20  ..** .** SQLite 
62f0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
6300: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
6310: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
6320: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64   xOpen.** method
6330: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
6340: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
6350: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6360: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6370: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
6380: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ].** </ul>.** .*
6390: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
63a0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
63b0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
63c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
63d0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
63e0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54  it is closed.  T
63f0: 68 69 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  his will always 
6400: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
6410: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 20 61 6e  .** databases an
6420: 64 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66  d journals and f
6430: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20  or subjournals. 
6440: 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   The .** [SQLITE
6450: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
6460: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
6470: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
6480: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
6490: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
64a0: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
64b0: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
64c0: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
64d0: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
64e0: 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a 20 53 70 61 63  ile..** .** Spac
64f0: 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  e to hold the  [
6500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
6510: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
6520: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
6530: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
6540: 6e 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  n is allocated b
6550: 79 20 63 61 6c 6c 65 72 20 28 74 68 65 20 53 51  y caller (the SQ
6560: 4c 69 74 65 20 63 6f 72 65 29 2e 20 0a 2a 2a 20  Lite core). .** 
6570: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 61  szOsFile bytes a
6580: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72  re allocated for
6590: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54   this object.  T
65a0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 0a  he xOpen method.
65b0: 2a 2a 20 66 69 6c 6c 73 20 69 6e 20 74 68 65 20  ** fills in the 
65c0: 61 6c 6c 6f 63 61 74 65 64 20 73 70 61 63 65 2e  allocated space.
65d0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67  .** .** The flag
65e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
65f0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 30  ccess() may be 0
6600: 20 28 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68   (to test for th
6610: 65 0a 2a 2a 20 65 78 69 73 74 61 6e 63 65 20 6f  e.** existance o
6620: 66 20 61 20 66 69 6c 65 29 20 6f 72 20 53 51 4c  f a file) or SQL
6630: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
6640: 52 49 54 45 20 74 6f 20 74 65 73 74 20 74 6f 20  RITE to test to 
6650: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
6660: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
6670: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 53 51   writable, or SQ
6680: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
6690: 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 74 65 73 74 20  ONLY.** to test 
66a0: 74 6f 20 73 65 65 20 69 66 20 61 20 66 69 6c 65  to see if a file
66b0: 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20   is read-only.  
66c0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
66d0: 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e  a .** directory.
66e0: 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77  .** .** SQLite w
66f0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
6700: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
6710: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66  athname+1 byte f
6720: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74  or.** the output
6730: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65   buffers for xGe
6740: 74 54 65 6d 70 4e 61 6d 65 20 61 6e 64 20 78 46  tTempName and xF
6750: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 0a 2a 2a 20  ullPathname..** 
6760: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
6770: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
6780: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
6790: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
67a0: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
67b0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
67c0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
67d0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
67e0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
67f0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
6800: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
6810: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
6820: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
6830: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
6840: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
6850: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
6860: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
6870: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
6880: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
6890: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
68a0: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
68b0: 6e 65 73 73 20 67 65 6e 65 72 61 74 65 64 2e 20  ness generated. 
68c0: 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29   The.** xSleep()
68d0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 20 74 68   method cause th
68e0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
68f0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
6900: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
6910: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
6920: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
6930: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
6940: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
6950: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
6960: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
6970: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a  rrent date and.*
6980: 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  * time..*/.typed
6990: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
69a0: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
69b0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
69c0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
69d0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
69e0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
69f0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
6a00: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
6a10: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
6a20: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
6a30: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
6a40: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
6a50: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
6a60: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
6a70: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
6a80: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
6a90: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
6aa0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
6ab0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
6ac0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
6ad0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
6ae0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
6af0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
6b00: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
6b10: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
6b20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
6b30: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
6b40: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
6b50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
6b60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
6b70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
6b90: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
6ba0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
6bb0: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
6bc0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
6bd0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
6be0: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
6bf0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
6c00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
6c10: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
6c20: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  ags);.  int (*xG
6c30: 65 74 54 65 6d 70 4e 61 6d 65 29 28 73 71 6c 69  etTempName)(sqli
6c40: 74 65 33 5f 76 66 73 2a 2c 20 63 68 61 72 20 2a  te3_vfs*, char *
6c50: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
6c60: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
6c70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
6c80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 63  t char *zName, c
6c90: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
6ca0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
6cb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
6cc0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
6cd0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
6ce0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
6cf0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
6d00: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
6d10: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
6d20: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
6d30: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
6d40: 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76  r *zSymbol);.  v
6d50: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
6d60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
6d70: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
6d80: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
6d90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
6da0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
6db0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
6dc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
6dd0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
6de0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
6df0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
6e00: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
6e10: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
6e20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
6e30: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
6e40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
6e50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
6e60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
6e70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
6e80: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
6e90: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
6ea0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
6eb0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
6ec0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
6ed0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
6ee0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
6ef0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
6f00: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
6f10: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
6f20: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
6f30: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
6f40: 0a 2a 2a 20 74 68 65 20 6b 69 6e 64 20 6f 66 20  .** the kind of 
6f50: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
6f60: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
6f70: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a  cess method is.*
6f80: 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20  * looking for.  
6f90: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
6fa0: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
6fb0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
6fc0: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74   simply checks t
6fd0: 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c  o see if the fil
6fe0: 65 20 65 78 69 73 74 73 2e 20 20 57 69 74 68 20  e exists.  With 
6ff0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
7000: 41 44 57 52 49 54 45 2c 0a 2a 2a 20 74 68 65 20  ADWRITE,.** the 
7010: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 63  xAccess method c
7020: 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20  hecks to see if 
7030: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
7040: 20 72 65 61 64 61 62 6c 65 0a 2a 2a 20 61 6e 64   readable.** and
7050: 20 77 72 69 74 61 62 6c 65 2e 20 20 57 69 74 68   writable.  With
7060: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
7070: 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73 20  EAD the xAccess 
7080: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
7090: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66   to see if the f
70a0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
70b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
70c0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
70d0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
70e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
70f0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
7100: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
7110: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
7120: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
7130: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
7140: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
7150: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  es.**.** This ro
7160: 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
7170: 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
7180: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
7190: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
71a0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
71b0: 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61  ture..** By defa
71c0: 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ult, SQLite API 
71d0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
71e0: 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69  one of only 26 i
71f0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
7200: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
7210: 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 74 65  des].  When exte
7220: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
7230: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
7240: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
7250: 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 65 20  , the repetoire 
7260: 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  of result codes 
7270: 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c  can be.** much l
7280: 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28 68  arger and can (h
7290: 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69 64  opefully) provid
72a0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
72b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
72c0: 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 20 6f  bout the cause o
72d0: 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  f an error..**.*
72e0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
72f0: 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65  ument is a boole
7300: 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 74 75  an value that tu
7310: 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  rns extended res
7320: 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20  ult.** codes on 
7330: 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 6e 64  and off.  Extend
7340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
7350: 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61 75  are off by defau
7360: 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61  lt for.** backwa
7370: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
7380: 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65 72  y with older ver
7390: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
73a0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
73b0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
73c0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
73d0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
73e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
73f0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
7400: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
7410: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
7420: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
7430: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
7440: 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c  teger key.** cal
7450: 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e  led the "rowid".
7460: 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c   The rowid is al
7470: 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 20 61  ways available a
7480: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a  s an undeclared.
7490: 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ** column named 
74a0: 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
74b0: 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 65 20  ROWID_.  If the 
74c0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
74d0: 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e  mn of.** type IN
74e0: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
74f0: 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  Y then that colu
7500: 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6e  mn is another an
7510: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 0a 2a   alias for the.*
7520: 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  * rowid..**.** T
7530: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
7540: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66  rns the rowid of
7550: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
7560: 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a 20   INSERT into.** 
7570: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
7580: 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  m the database c
7590: 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e 20  onnection given 
75a0: 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a  in the first .**
75b0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e   argument.  If n
75c0: 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 20 65  o inserts have e
75d0: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
75e0: 74 68 69 73 20 64 61 74 61 62 61 73 65 0a 2a 2a  this database.**
75f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
7600: 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
7610: 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52  *.** If an INSER
7620: 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  T occurs within 
7630: 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
7640: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
7650: 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77  .** inserted row
7660: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
7670: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
7680: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
7690: 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ger.** is runnin
76a0: 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65  g.  But once the
76b0: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
76c0: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
76d0: 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68  eturned.** by th
76e0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
76f0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
7700: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
7710: 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67  fore the.** trig
7720: 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a  ger fired..**.**
7730: 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
7740: 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e  ad does a new in
7750: 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  sert on the same
7760: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7770: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68  tion.** while th
7780: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
7790: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
77a0: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
77b0: 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a  insert rowid,.**
77c0: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
77d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72   value of this r
77e0: 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
77f0: 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ned..*/.sqlite3_
7800: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
7810: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
7820: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
7830: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
7840: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
7850: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
7860: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
7870: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
7880: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
7890: 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
78a0: 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 69  changed.** (or i
78b0: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
78c0: 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ed) by the most 
78d0: 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61 74 65  recent SQL state
78e0: 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63  ment.  Only.** c
78f0: 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
7900: 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
7910: 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ed by the INSERT
7920: 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20  , UPDATE, or.** 
7930: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
7940: 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
7950: 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
7960: 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
7970: 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63  iggers are not c
7980: 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74 68 65  ounted.  Use the
7990: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
79a0: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
79b0: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
79c0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
79d0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
79e0: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
79f0: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
7a00: 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68  .**.** Within th
7a10: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
7a20: 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ger, the sqlite3
7a30: 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
7a40: 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63  face can be.** c
7a50: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
7a60: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
7a70: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
7a80: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
7a90: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
7aa0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
7ab0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
7ac0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
7ad0: 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  the trigger..**.
7ae0: 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61  ** All changes a
7af0: 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e  re counted, even
7b00: 20 69 66 20 74 68 65 79 20 77 65 72 65 20 6c 61   if they were la
7b10: 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a  ter undone by a.
7b20: 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41  ** ROLLBACK or A
7b30: 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c 20 63  BORT.  Except, c
7b40: 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74 65  hanges associate
7b50: 64 20 77 69 74 68 20 63 72 65 61 74 69 6e 67 20  d with creating 
7b60: 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20  and.** dropping 
7b70: 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 63  tables are not c
7b80: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  ounted..**.** If
7b90: 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f   a callback invo
7ba0: 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  kes [sqlite3_exe
7bb0: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
7bc0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
7bd0: 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  vely,.** then th
7be0: 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  e changes in the
7bf0: 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69 76   inner, recursiv
7c00: 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74  e call are count
7c10: 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a 20 77  ed together.** w
7c20: 69 74 68 20 74 68 65 20 63 68 61 6e 67 65 73 20  ith the changes 
7c30: 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61 6c  in the outer cal
7c40: 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  l..**.** SQLite 
7c50: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
7c60: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
7c70: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
7c80: 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  ut a WHERE claus
7c90: 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67  e.** by dropping
7ca0: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
7cb0: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
7cc0: 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72  s is much faster
7cd0: 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74   than going.** t
7ce0: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
7cf0: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
7d00: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  lements from the
7d10: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73   table.)  Becaus
7d20: 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74  e of.** this opt
7d30: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63  imization, the c
7d40: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20  hange count for 
7d50: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
7d60: 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a  le" will be.** z
7d70: 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ero regardless o
7d80: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
7d90: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
7da0: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  re originally in
7db0: 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54   the.** table. T
7dc0: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74  o get an accurat
7dd0: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  e count of the n
7de0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65  umber of rows de
7df0: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44  leted, use.** "D
7e00: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
7e10: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61   WHERE 1" instea
7e20: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  d..**.** If anot
7e30: 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 73  her thread makes
7e40: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
7e50: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
7e60: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
7e70: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
7e80: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
7e90: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
7ea0: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  of this routine.
7eb0: 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
7ec0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
7ed0: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
7ee0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
7ef0: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
7f00: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
7f10: 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  d.***.** This fu
7f20: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
7f30: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
7f40: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
7f50: 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64  have been.** mod
7f60: 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54 2c  ified by INSERT,
7f70: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
7f80: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  E statements sin
7f90: 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
7fa0: 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70  handle.** was op
7fb0: 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c 75  ened. This inclu
7fc0: 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53 45  des UPDATE, INSE
7fd0: 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73 74  RT and DELETE st
7fe0: 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74 65  atements execute
7ff0: 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  d.** as part of 
8000: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
8010: 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72  . All changes ar
8020: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
8030: 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61 74  n as the.** stat
8040: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
8050: 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
8060: 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
8070: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
8080: 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73  .** passed to [s
8090: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
80a0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
80b0: 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lise()])..**.** 
80c0: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
80d0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d 20  lite3_change()] 
80e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
80f0: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
8100: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
8110: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
8120: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
8130: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
8140: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
8150: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
8160: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
8170: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
8180: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
8190: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
81a0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
81b0: 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  form the table.)
81c0: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
81d0: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
81e0: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
81f0: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
8200: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
8210: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
8220: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
8230: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
8240: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
8250: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
8260: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
8270: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
8280: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
8290: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
82a0: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
82b0: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
82c0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
82d0: 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
82e0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
82f0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
8300: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8310: 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72  .** while this r
8320: 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
8330: 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  g then the retur
8340: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
8350: 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e  routine.** is un
8360: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
8370: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
8380: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
8390: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
83a0: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
83b0: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
83c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
83d0: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
83e0: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
83f0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
8400: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
8410: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
8420: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 20  t opportunity.  
8430: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
8440: 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
8450: 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
8460: 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
8470: 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
8480: 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
8490: 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
84a0: 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
84b0: 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
84c0: 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
84d0: 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
84e0: 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20  * It is safe to 
84f0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
8500: 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
8510: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
8520: 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
8530: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
8540: 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
8550: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
8560: 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
8570: 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
8580: 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
8590: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
85a0: 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73  ction that.** is
85b0: 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
85c0: 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
85d0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
85e0: 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
85f0: 20 54 68 65 20 53 51 4c 20 6f 70 65 72 61 74 69   The SQL operati
8600: 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
8610: 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
8620: 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
8630: 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20  RUPT]..** If an 
8640: 69 6e 74 65 72 72 75 70 74 65 64 20 6f 70 65 72  interrupted oper
8650: 61 74 69 6f 6e 20 77 61 73 20 61 6e 20 75 70 64  ation was an upd
8660: 61 74 65 20 74 68 61 74 20 69 73 20 69 6e 73 69  ate that is insi
8670: 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  de an.** explici
8680: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
8690: 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
86a0: 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20  ransaction will 
86b0: 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63  be rolled.** bac
86c0: 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
86d0: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
86e0: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
86f0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
8700: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
8710: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
8720: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
8730: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
8740: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 74 72  ctions return tr
8750: 75 65 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ue if the given 
8760: 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63 6f 6d  input string com
8770: 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72  prises.** one or
8780: 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53   more complete S
8790: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 46  QL statements. F
87a0: 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  or the sqlite3_c
87b0: 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c 6c 2c 0a  omplete() call,.
87c0: 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ** the parameter
87d0: 20 6d 75 73 74 20 62 65 20 61 20 6e 75 6c 2d 74   must be a nul-t
87e0: 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
87f0: 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73  string. For.** s
8800: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
8810: 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65 72 6d 69  6(), a nul-termi
8820: 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20 62 79  nated machine by
8830: 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31 36 20  te order UTF-16 
8840: 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71  string.** is req
8850: 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
8860: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
8870: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
8880: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
8890: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
88a0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
88b0: 6e 74 65 72 65 64 20 74 65 78 74 20 66 6f 72 6d  ntered text form
88c0: 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f  s one or more co
88d0: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
88e0: 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69 66 20 61  ments or.** if a
88f0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
8900: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
8910: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 73 74 61   sending the sta
8920: 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20  tements into.** 
8930: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
8940: 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72 69 74 68  ng. The algorith
8950: 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20 49 66  m is simple.  If
8960: 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74 20 74 6f   the .** last to
8970: 6b 65 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 73  ken other than s
8980: 70 61 63 65 73 20 61 6e 64 20 63 6f 6d 6d 65 6e  paces and commen
8990: 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f  ts is a semicolo
89a0: 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 20 0a  n, then return .
89b0: 2a 2a 20 74 72 75 65 2e 20 20 41 63 74 75 61 6c  ** true.  Actual
89c0: 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72 69 74 68  ly, the algorith
89d0: 6d 20 69 73 20 61 20 6c 69 74 74 6c 65 20 6d 6f  m is a little mo
89e0: 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 74  re complicated t
89f0: 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69 6e 20 6f  han that.** in o
8a00: 72 64 65 72 20 74 6f 20 64 65 61 6c 20 77 69 74  rder to deal wit
8a10: 68 20 74 72 69 67 67 65 72 73 2c 20 62 75 74 20  h triggers, but 
8a20: 74 68 65 20 62 61 73 69 63 20 69 64 65 61 20 69  the basic idea i
8a30: 73 20 74 68 65 20 73 61 6d 65 3a 20 20 74 68 65  s the same:  the
8a40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
8a50: 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20 75 6e   not complete un
8a60: 6c 65 73 73 20 69 74 20 65 6e 64 73 20 69 6e 20  less it ends in 
8a70: 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a  a semicolon..*/.
8a80: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
8a90: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
8aa0: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
8ab0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
8ac0: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
8ad0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8ae0: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
8af0: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
8b00: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
8b10: 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  s.**.** This rou
8b20: 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20  tine identifies 
8b30: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
8b40: 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
8b50: 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
8b60: 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74  never an attempt
8b70: 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
8b80: 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
8b90: 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68  e .** that anoth
8ba0: 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f  er thread or pro
8bb0: 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
8bc0: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
8bd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
8be0: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
8bf0: 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65  USY].** (or some
8c00: 74 69 6d 65 73 20 5b 53 51 4c 49 54 45 5f 49 4f  times [SQLITE_IO
8c10: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a  ERR_BLOCKED]).**
8c20: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
8c30: 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
8c40: 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
8c50: 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62  ock..** If the b
8c60: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
8c70: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
8c80: 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77  he.** callback w
8c90: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
8ca0: 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
8cb0: 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74  s.  The.** first
8cc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8cd0: 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
8ce0: 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
8cf0: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
8d00: 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
8d10: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72  gument to this r
8d20: 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63  outine.  The sec
8d30: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
8d40: 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  ** the handler i
8d50: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
8d60: 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
8d70: 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
8d80: 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
8d90: 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
8da0: 20 65 76 65 6e 74 2e 20 49 66 20 74 68 65 0a 2a   event. If the.*
8db0: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
8dc0: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
8dd0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
8de0: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
8df0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
8e00: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
8e10: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
8e20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
8e30: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
8e40: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
8e50: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
8e60: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
8e70: 74 68 65 72 20 61 74 74 65 6d 70 74 20 69 73 20  ther attempt is 
8e80: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
8e90: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 6f 72  .** database for
8ea0: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
8eb0: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
8ec0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
8ed0: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
8ee0: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
8ef0: 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20  arantee that.** 
8f00: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
8f10: 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ed when there is
8f20: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
8f30: 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  ..** If SQLite d
8f40: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
8f50: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
8f60: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
8f70: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
8f80: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
8f90: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
8fa0: 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  USY] instead..**
8fb0: 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
8fc0: 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
8fd0: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
8fe0: 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
8ff0: 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
9000: 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
9010: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
9020: 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
9030: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
9040: 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
9050: 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
9060: 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
9070: 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
9080: 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
9090: 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
90a0: 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
90b0: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
90c0: 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
90d0: 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
90e0: 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
90f0: 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
9100: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
9110: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
9120: 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
9130: 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
9140: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
9150: 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
9160: 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
9170: 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
9180: 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
9190: 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
91a0: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
91b0: 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
91c0: 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
91d0: 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
91e0: 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
91f0: 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
9200: 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
9210: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
9220: 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
9230: 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
9240: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
9250: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
9260: 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
9270: 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
9280: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
9290: 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a 20  LOCKED] when.** 
92a0: 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
92b0: 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
92c0: 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
92d0: 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
92e0: 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
92f0: 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
9300: 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
9310: 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
9320: 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
9330: 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
9340: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9350: 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
9360: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
9370: 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
9380: 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
9390: 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
93a0: 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
93b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
93c0: 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
93d0: 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
93e0: 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
93f0: 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
9400: 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
9410: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
9420: 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
9430: 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
9440: 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
9450: 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
9460: 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
9470: 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
9480: 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
9490: 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
94a0: 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
94b0: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
94c0: 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
94d0: 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
94e0: 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
94f0: 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
9500: 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
9510: 67 65 73 2e 20 53 65 65 20 74 68 65 0a 2a 2a 20  ges. See the.** 
9520: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f  <a href="http://
9530: 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63  www.sqlite.org/c
9540: 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
9550: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
9560: 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
9570: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
9580: 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
9590: 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
95a0: 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
95b0: 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
95c0: 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20  portant..**..** 
95d0: 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e 74  Sqlite is re-ent
95e0: 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75 73  rant, so the bus
95f0: 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73 74  y handler may st
9600: 61 72 74 20 61 20 6e 65 77 20 71 75 65 72 79 2e  art a new query.
9610: 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74 20   .** (It is not 
9620: 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f 6e 65  clear why anyone
9630: 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77 61 6e   would every wan
9640: 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20 62 75  t to do this, bu
9650: 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77  t it.** is allow
9660: 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29 20  ed, in theory.) 
9670: 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68 61   But the busy ha
9680: 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63 6c  ndler may not cl
9690: 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ose the.** datab
96a0: 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68  ase.  Closing th
96b0: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
96c0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  a busy handler w
96d0: 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20 64  ill delete .** d
96e0: 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
96f0: 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 68  ut from under th
9700: 65 20 65 78 65 63 75 74 69 6e 67 20 71 75 65 72  e executing quer
9710: 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 70  y and will .** p
9720: 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20 69  robably result i
9730: 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
9740: 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
9750: 72 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e 0a 2a  runtime error..*
9760: 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
9770: 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
9780: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
9790: 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61  ined for each da
97a0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
97b0: 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61  tion.  Setting a
97c0: 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
97d0: 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65  r clears any pre
97e0: 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f  vious one..** No
97f0: 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
9800: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
9810: 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c  meout()] will al
9820: 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a  so set or clear.
9830: 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
9840: 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ler..**.** When 
9850: 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b 73 71  operating in [sq
9860: 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
9870: 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61 72  red_cache | shar
9880: 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 0a  ed cache mode],.
9890: 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** only a single
98a0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
98b0: 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66 6f 72  n be defined for
98c0: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 66   each database f
98d0: 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74 77  ile..** So if tw
98e0: 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  o database conne
98f0: 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61 20 73  ctions share a s
9900: 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74 68 65  ingle cache, the
9910: 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74 68  n changing.** th
9920: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6f  e busy handler o
9930: 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  n one connection
9940: 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e 67   will also chang
9950: 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  e the busy.** ha
9960: 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f 74 68  ndler in the oth
9970: 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  er connection.  
9980: 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  The busy handler
9990: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69   is invoked.** i
99a0: 6e 20 74 68 65 20 74 68 72 65 61 64 20 74 68 61  n the thread tha
99b0: 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20 77 68  t was running wh
99c0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 42 55  en the SQLITE_BU
99d0: 53 59 20 77 61 73 20 68 69 74 2e 0a 2a 2f 0a 69  SY was hit..*/.i
99e0: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
99f0: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
9a00: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
9a10: 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
9a20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
9a30: 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
9a40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
9a50: 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79 20  ine sets a busy 
9a60: 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c 65  handler that sle
9a70: 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20  eps for a while 
9a80: 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20  when a.** table 
9a90: 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20  is locked.  The 
9aa0: 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65  handler will sle
9ab0: 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
9ac0: 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c  s until .** at l
9ad0: 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
9ae0: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
9af0: 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e  ng have been don
9b00: 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73  e.  After.** "ms
9b10: 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
9b20: 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 20  f sleeping, the 
9b30: 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
9b40: 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 65  0 which.** cause
9b50: 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
9b60: 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53 51  )] to return [SQ
9b70: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
9b80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
9b90: 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  KED]..**.** Call
9ba0: 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
9bb0: 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
9bc0: 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
9bd0: 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
9be0: 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
9bf0: 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
9c00: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
9c10: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
9c20: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
9c30: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9c40: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9c50: 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  on.  If another 
9c60: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61 73  busy handler was
9c70: 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75   defined  .** (u
9c80: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
9c90: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
9ca0: 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
9cb0: 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
9cc0: 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
9cd0: 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
9ce0: 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  red..*/.int sqli
9cf0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
9d00: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
9d10: 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
9d20: 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
9d30: 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
9d40: 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
9d50: 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72 6f  .** This next ro
9d60: 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e 76 65  utine is a conve
9d70: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
9d80: 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  round [sqlite3_e
9d90: 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65  xec()]..** Inste
9da0: 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61  ad of invoking a
9db0: 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 63   user-supplied c
9dc0: 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 68  allback for each
9dd0: 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72   row of the.** r
9de0: 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 74  esult, this rout
9df0: 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65 61  ine remembers ea
9e00: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  ch row of the re
9e10: 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  sult in memory.*
9e20: 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
9e30: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9e40: 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 73  )], then returns
9e50: 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73 75   all of the resu
9e60: 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  lt after the.** 
9e70: 71 75 65 72 79 20 68 61 73 20 66 69 6e 69 73 68  query has finish
9e80: 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ed. .**.** As an
9e90: 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73   example, suppos
9ea0: 65 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  e the query resu
9eb0: 6c 74 20 77 68 65 72 65 20 74 68 69 73 20 74 61  lt where this ta
9ec0: 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ble:.**.** <bloc
9ed0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
9ee0: 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
9ef0: 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
9f00: 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
9f10: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
9f20: 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
9f30: 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
9f40: 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
9f50: 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
9f60: 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
9f70: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
9f80: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e>.**.** If the 
9f90: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 77 65 72  3rd argument wer
9fa0: 65 20 26 61 7a 52 65 73 75 6c 74 20 74 68 65 6e  e &azResult then
9fb0: 20 61 66 74 65 72 20 74 68 65 20 66 75 6e 63 74   after the funct
9fc0: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ion returns.** a
9fd0: 7a 52 65 73 75 6c 74 20 77 69 6c 6c 20 63 6f 6e  zResult will con
9fe0: 74 61 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  tain the followi
9ff0: 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c  ng data:.**.** <
a000: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
a010: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a020: 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
a030: 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
a040: 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
a050: 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
a060: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
a070: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
a080: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
a090: 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
a0a0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
a0b0: 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
a0c0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
a0d0: 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
a0e0: 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
a0f0: 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
a100: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
a110: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a120: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
a130: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
a140: 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74  >.**.** Notice t
a150: 68 61 74 20 74 68 65 72 65 20 69 73 20 61 6e 20  hat there is an 
a160: 65 78 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74  extra row of dat
a170: 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  a containing the
a180: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65   column.** heade
a190: 72 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72  rs.  But the *nr
a1a0: 6f 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  ow return value 
a1b0: 69 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63  is still 3.  *nc
a1c0: 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20  olumn is.** set 
a1d0: 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61  to 2.  In genera
a1e0: 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  l, the number of
a1f0: 20 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64   values inserted
a200: 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a   into azResult.*
a210: 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f  * will be ((*nro
a220: 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d  w) + 1)*(*ncolum
a230: 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  n)..**.** After 
a240: 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
a250: 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
a260: 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75  d using the resu
a270: 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a  lt, it should .*
a280: 2a 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  * pass the resul
a290: 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
a2a0: 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
a2b0: 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
a2c0: 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74  to .** release t
a2d0: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
a2e0: 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42  as malloc-ed.  B
a2f0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
a300: 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  y the .** [sqlit
a310: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
a320: 70 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e  pens, the callin
a330: 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
a340: 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
a350: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
a360: 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
a370: 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  Only [sqlite3_fr
a380: 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
a390: 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a  ble to release .
a3a0: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  ** the memory pr
a3b0: 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
a3c0: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  y..**.** The ret
a3d0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
a3e0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
a3f0: 20 73 61 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73   same as from [s
a400: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a  qlite3_exec()]..
a410: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
a420: 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
a430: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
a440: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
a450: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
a460: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
a470: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
a480: 65 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63 68  executed */.  ch
a490: 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20  ar ***resultp,  
a4a0: 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20 77       /* Result w
a4b0: 72 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61 72  ritten to a char
a4c0: 20 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73 20   *[]  that this 
a4d0: 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69  points to */.  i
a4e0: 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20  nt *nrow,       
a4f0: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
a500: 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
a510: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
a520: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20   int *ncolumn,  
a530: 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
a540: 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
a550: 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
a560: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
a570: 6d 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20  msg          /* 
a580: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
a590: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
a5a0: 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
a5b0: 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
a5c0: 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
a5d0: 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
a5e0: 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
a5f0: 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
a600: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a610: 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
a620: 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
a630: 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
a640: 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
a650: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
a660: 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
a670: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
a680: 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
a690: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
a6a0: 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
a6b0: 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
a6c0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a6d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a6e0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
a6f0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
a700: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
a710: 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
a720: 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
a730: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42  ite3_free()].  B
a740: 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
a750: 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
a760: 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
a770: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
a780: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
a790: 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
a7a0: 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
a7b0: 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
a7c0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
a7d0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
a7e0: 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
a7f0: 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
a800: 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
a810: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
a820: 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
a830: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
a840: 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
a850: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
a860: 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
a870: 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
a880: 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
a890: 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20  arameter.  Note 
a8a0: 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
a8b0: 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
a8c0: 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
a8d0: 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
a8e0: 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
a8f0: 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
a900: 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
a910: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
a920: 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
a930: 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
a940: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
a950: 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
a960: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
a970: 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
a980: 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
a990: 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
a9a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
a9b0: 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
a9c0: 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
a9d0: 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
a9e0: 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
a9f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
aa00: 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
aa10: 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
aa20: 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
aa30: 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
aa40: 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
aa50: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
aa60: 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
aa70: 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
aa80: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
aa90: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
aaa0: 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
aab0: 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
aac0: 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
aad0: 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
aae0: 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
aaf0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
ab00: 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
ab10: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
ab20: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
ab30: 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
ab40: 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
ab50: 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
ab60: 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
ab70: 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
ab80: 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
ab90: 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
aba0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
abb0: 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
abc0: 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
abd0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
abe0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
abf0: 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
ac00: 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
ac10: 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
ac20: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
ac30: 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
ac40: 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
ac50: 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
ac60: 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20  he usual printf 
ac70: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
ac80: 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
ac90: 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
aca0: 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
acb0: 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
acc0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
acd0: 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
ace0: 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
acf0: 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
ad00: 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
ad10: 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
ad20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
ad30: 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
ad40: 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
ad50: 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
ad60: 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
ad70: 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
ad80: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
ad90: 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
ada0: 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
adb0: 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
adc0: 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
add0: 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
ade0: 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
adf0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
ae00: 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
ae10: 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e  e, so some strin
ae20: 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61  g variable conta
ae30: 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
ae40: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
ae50: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
ae60: 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
ae70: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
ae80: 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
ae90: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
aea0: 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
aeb0: 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
aec0: 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
aed0: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
aee0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
aef0: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
af00: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
af10: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
af20: 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
af30: 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
af40: 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
af50: 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
af60: 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
af70: 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
af80: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
af90: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
afa0: 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
afb0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
afc0: 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
afd0: 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
afe0: 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
aff0: 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
b000: 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
b010: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
b020: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
b030: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
b040: 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
b050: 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
b060: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
b070: 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
b080: 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
b090: 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
b0a0: 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
b0b0: 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
b0c0: 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
b0d0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
b0e0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
b0f0: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
b100: 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
b110: 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
b120: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
b130: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
b140: 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
b150: 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
b160: 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
b170: 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a  eneral rule you.
b180: 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  ** should always
b190: 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
b1a0: 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
b1b0: 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
b1c0: 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65   string .** lite
b1d0: 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
b1e0: 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
b1f0: 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
b200: 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
b210: 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
b220: 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
b230: 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
b240: 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70  ng.  Or if the p
b250: 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
b260: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74  argument.** list
b270: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b280: 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
b290: 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
b2a0: 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67  L" (without sing
b2b0: 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e  le.** quotes) in
b2c0: 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51   place of the %Q
b2d0: 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f   option.  So, fo
b2e0: 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
b2f0: 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
b300: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
b310: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
b320: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
b330: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
b340: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
b350: 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
b360: 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
b370: 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
b380: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
b390: 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
b3a0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
b3b0: 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
b3c0: 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
b3d0: 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
b3e0: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
b3f0: 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
b400: 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
b410: 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
b420: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
b430: 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72  .** The "%z" for
b440: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
b450: 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b  orks exactly lik
b460: 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a  e "%s" with the.
b470: 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
b480: 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
b490: 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
b4a0: 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
b4b0: 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
b4c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
b4d0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
b4e0: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a   input string..*
b4f0: 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
b500: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
b510: 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
b520: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
b530: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
b540: 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
b550: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
b560: 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
b570: 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
b580: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
b590: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
b5a0: 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
b5b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
b5c0: 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
b5d0: 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
b5e0: 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
b5f0: 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
b600: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
b610: 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
b620: 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
b630: 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
b640: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
b650: 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f  m uses the mallo
b660: 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a  c(), realloc().*
b670: 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  * and free() pro
b680: 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
b690: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
b6a0: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a    However, if .*
b6b0: 2a 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  * SQLite is comp
b6c0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 6f  iled with the fo
b6d0: 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f  llowing C prepro
b6e0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a  cessor macro.**.
b6f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20  ** <blockquote> 
b700: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
b710: 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 3c 2f  RY_ALLOCATION </
b720: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
b730: 2a 20 74 68 65 6e 20 6e 6f 20 69 6d 70 6c 65 6d  * then no implem
b740: 65 6e 74 61 74 69 6f 6e 20 69 73 20 70 72 6f 76  entation is prov
b750: 69 64 65 64 20 66 6f 72 20 74 68 65 73 65 20 72  ided for these r
b760: 6f 75 74 69 6e 65 73 20 62 79 0a 2a 2a 20 53 51  outines by.** SQ
b770: 4c 69 74 65 2e 20 20 54 68 65 20 61 70 70 6c 69  Lite.  The appli
b780: 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b  cation that link
b790: 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
b7a0: 20 69 73 0a 2a 2a 20 65 78 70 65 63 74 65 64 20   is.** expected 
b7b0: 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f  to provide its o
b7c0: 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  wn implementatio
b7d0: 6e 2e 20 20 49 66 20 74 68 65 20 61 70 70 6c 69  n.  If the appli
b7e0: 63 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 70  cation.** does p
b7f0: 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69  rovide its own i
b800: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
b810: 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
b820: 2c 20 74 68 65 6e 0a 2a 2a 20 69 74 20 6d 75 73  , then.** it mus
b830: 74 20 61 6c 73 6f 20 70 72 6f 76 69 64 65 20 61  t also provide a
b840: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
b850: 20 66 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   for.** [sqlite3
b860: 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d  _memory_alarm()]
b870: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78 63 65 70  ..**.** <b>Excep
b880: 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65 20 77 69  tion:</b> The wi
b890: 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
b8a0: 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
b8b0: 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
b8c0: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
b8d0: 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
b8e0: 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
b8f0: 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
b900: 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
b910: 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
b920: 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
b930: 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
b940: 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
b950: 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 69 6e  e particular win
b960: 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
b970: 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
b980: 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
b990: 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
b9a0: 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
b9b0: 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
b9c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
b9d0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
b9e0: 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
b9f0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
ba00: 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
ba10: 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
ba20: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
ba30: 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
ba40: 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
ba50: 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
ba60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
ba70: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
ba80: 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
ba90: 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 74  In addition to t
baa0: 68 65 20 62 61 73 69 63 20 74 68 72 65 65 20 61  he basic three a
bab0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
bac0: 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
bad0: 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
bae0: 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
baf0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
bb00: 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  c()],.** the mem
bb10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
bb20: 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65  ubsystem include
bb30: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74  d with the SQLit
bb40: 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20 70 72 6f  e.** sources pro
bb50: 76 69 64 65 73 20 74 68 65 20 69 6e 74 65 72 66  vides the interf
bb60: 61 63 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  aces shown below
bb70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
bb80: 74 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 72  t of these two r
bb90: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
bba0: 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  the amount of me
bbb0: 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72 65 6e 74  mory .** current
bbc0: 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
bbd0: 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
bbe0: 20 66 72 65 65 64 29 2e 20 20 54 68 65 20 73 65   freed).  The se
bbf0: 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 73 20  cond.** returns 
bc00: 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 73 74  the largest inst
bc10: 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f 75 6e 74  antaneous amount
bc20: 20 6f 66 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a   of outstanding.
bc30: 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20  ** memory.  The 
bc40: 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69  highwater mark i
bc50: 73 20 72 65 73 65 74 20 69 66 20 74 68 65 20 61  s reset if the a
bc60: 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 72  rgument is.** tr
bc70: 75 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ue.  The SQLite 
bc80: 63 6f 72 65 20 64 6f 65 73 20 6e 6f 74 20 75 73  core does not us
bc90: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
bca0: 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 6e  e routines.** an
bcb0: 64 20 73 6f 20 74 68 65 79 20 64 6f 20 6e 6f 74  d so they do not
bcc0: 20 68 61 76 65 20 74 6f 20 62 65 20 69 6d 70 6c   have to be impl
bcd0: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 61  emented by the a
bce0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 69 66  pplication.** if
bcf0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
bd00: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 69  ORY_ALLOCATION i
bd10: 73 20 64 65 66 69 6e 65 64 2e 20 20 54 68 65 73  s defined.  Thes
bd20: 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
bd30: 65 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  e provided by th
bd40: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
bd50: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 64   subsystem for d
bd60: 69 61 67 6e 6f 73 74 69 63 0a 2a 2a 20 70 75 72  iagnostic.** pur
bd70: 70 6f 73 65 73 2e 0a 2a 2f 0a 73 71 6c 69 74 65  poses..*/.sqlite
bd80: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
bd90: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
bda0: 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
bdb0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
bdc0: 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
bdd0: 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
bde0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
bdf0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61  y Allocation Ala
be00: 72 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  rms.**.** The [s
be10: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
be20: 61 72 6d 5d 20 72 6f 75 74 69 6e 65 20 69 73 20  arm] routine is 
be30: 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
be40: 0a 2a 2a 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f  .** a callback o
be50: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
be60: 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a  ion events..**.*
be70: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
be80: 65 67 69 73 74 65 72 73 20 6f 72 20 63 6c 65 61  egisters or clea
be90: 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 73 20 74  rs a callbacks t
bea0: 68 61 74 20 66 69 72 65 73 20 77 68 65 6e 0a 2a  hat fires when.*
beb0: 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * the amount of 
bec0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
bed0: 20 65 78 63 65 65 64 73 20 69 54 68 72 65 73 68   exceeds iThresh
bee0: 6f 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20  old.  Only.** a 
bef0: 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
bf00: 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
bf10: 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  d at a time.  Ea
bf20: 63 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ch call.** to [s
bf30: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
bf40: 61 72 6d 28 29 5d 20 6f 76 65 72 77 72 69 74 65  arm()] overwrite
bf50: 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  s the previous c
bf60: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
bf70: 63 61 6c 6c 62 61 63 6b 20 69 73 20 64 69 73 61  callback is disa
bf80: 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
bf90: 78 43 61 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e  xCallback to a N
bfa0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a  ULL.** pointer..
bfb0: 2a 2a 20 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d  ** .** The param
bfc0: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
bfd0: 6c 62 61 63 6b 20 61 72 65 20 74 68 65 20 70 41  lback are the pA
bfe0: 72 67 20 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a  rg value, the .*
bff0: 2a 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  * amount of memo
c000: 72 79 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  ry currently in 
c010: 75 73 65 2c 20 61 6e 64 20 74 68 65 20 73 69 7a  use, and the siz
c020: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
c030: 63 61 74 69 6f 6e 20 74 68 61 74 20 70 72 6f 76  cation that prov
c040: 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
c050: 6b 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  k.  The callback
c060: 20 77 69 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61   will.** presuma
c070: 62 6c 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  bly invoke [sqli
c080: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66  te3_free()] to f
c090: 72 65 65 20 75 70 20 6d 65 6d 6f 72 79 20 73 70  ree up memory sp
c0a0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ace..** The call
c0b0: 62 61 63 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20  back may invoke 
c0c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c0d0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
c0e0: 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74  ealloc()].** but
c0f0: 20 69 66 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20   if it does, no 
c100: 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  additional callb
c110: 61 63 6b 73 20 77 69 6c 6c 20 62 65 20 69 6e 76  acks will be inv
c120: 6f 6b 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 72  oked by.** the r
c130: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a  ecursive calls..
c140: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
c150: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
c160: 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
c170: 77 6f 72 6b 73 20 62 79 20 72 65 67 69 73 74 65  works by registe
c180: 72 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  ring.** a memory
c190: 20 61 6c 61 72 6d 20 61 74 20 74 68 65 20 73 6f   alarm at the so
c1a0: 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
c1b0: 64 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b  d invoking .** [
c1c0: 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
c1d0: 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 20 74 68 65  memory()] in the
c1e0: 20 61 6c 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e   alarm callback.
c1f0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a    Application.**
c200: 20 70 72 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64   programs should
c210: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
c220: 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
c230: 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d  _memory_alarm()]
c240: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62 65  .** interface be
c250: 63 61 75 73 65 20 64 6f 69 6e 67 20 73 6f 20 77  cause doing so w
c260: 69 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69  ill interfere wi
c270: 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
c280: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
c290: 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e 20 20 54  it()] module.  T
c2a0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
c2b0: 20 65 78 70 6f 73 65 64 0a 2a 2a 20 6f 6e 6c 79   exposed.** only
c2c0: 20 73 6f 20 74 68 61 74 20 61 70 70 6c 69 63 61   so that applica
c2d0: 74 69 6f 6e 73 20 63 61 6e 20 70 72 6f 76 69 64  tions can provid
c2e0: 65 20 74 68 65 69 72 20 6f 77 6e 0a 2a 2a 20 61  e their own.** a
c2f0: 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
c300: 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
c310: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69  he SQLite core i
c320: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
c330: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  th SQLITE_OMIT_M
c340: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
c350: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c360: 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a 20  _memory_alarm(. 
c370: 20 76 6f 69 64 28 2a 78 43 61 6c 6c 62 61 63 6b   void(*xCallback
c380: 29 28 76 6f 69 64 20 2a 70 41 72 67 2c 20 73 71  )(void *pArg, sq
c390: 6c 69 74 65 33 5f 69 6e 74 36 34 20 75 73 65 64  lite3_int64 used
c3a0: 2c 20 69 6e 74 20 4e 29 2c 0a 20 20 76 6f 69 64  , int N),.  void
c3b0: 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c 69 74 65   *pArg,.  sqlite
c3c0: 33 5f 69 6e 74 36 34 20 69 54 68 72 65 73 68 6f  3_int64 iThresho
c3d0: 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ld.);.../*.** CA
c3e0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
c3f0: 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
c400: 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 2a  on Callbacks.***
c410: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
c420: 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
c430: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
c440: 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65   with the SQLite
c450: 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 54   library.  .** T
c460: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
c470: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
c480: 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
c490: 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
c4a0: 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
c4b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
c4c0: 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
c4d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
c4e0: 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
c4f0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
c500: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
c510: 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
c520: 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
c530: 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
c540: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
c550: 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
c560: 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
c570: 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
c580: 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
c590: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
c5a0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
c5b0: 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
c5c0: 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
c5d0: 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
c5e0: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
c5f0: 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
c600: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 6f  urn SQLITE_OK to
c610: 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
c620: 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
c630: 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
c640: 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
c650: 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
c660: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
c670: 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
c680: 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
c690: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
c6a0: 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
c6b0: 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
c6c0: 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
c6d0: 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
c6e0: 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 70  ror.  .**.** Dep
c6f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 63  ending on the ac
c700: 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 54  tion, the [SQLIT
c710: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
c720: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 75  QLITE_DENY] retu
c730: 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 68  rn.** codes migh
c740: 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e 67  t mean something
c750: 20 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74 68   different or th
c760: 65 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 68  ey might mean th
c770: 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 2e  e same.** thing.
c780: 20 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20    If the action 
c790: 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  is, for example,
c7a0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 65   to perform a de
c7b0: 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a 2a  lete opertion,.*
c7c0: 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 49  * then [SQLITE_I
c7d0: 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c 49  GNORE] and [SQLI
c7e0: 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 61  TE_DENY] both ca
c7f0: 75 73 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  use the statemen
c800: 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a 2a  t compilation.**
c810: 20 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61 6e   to fail with an
c820: 20 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66 20   error.  But if 
c830: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74 6f  the action is to
c840: 20 72 65 61 64 20 61 20 73 70 65 63 69 66 69 63   read a specific
c850: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d 20   column.** from 
c860: 61 20 73 70 65 63 69 66 69 63 20 74 61 62 6c 65  a specific table
c870: 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 44  , then [SQLITE_D
c880: 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 20  ENY] will cause 
c890: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 74  the entire.** st
c8a0: 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c 20  atement to fail 
c8b0: 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  but [SQLITE_IGNO
c8c0: 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 61  RE] will cause a
c8d0: 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 62   NULL value to b
c8e0: 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 61  e.** read instea
c8f0: 64 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c 20  d of the actual 
c900: 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a  column value..**
c910: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
c920: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
c930: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
c940: 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
c950: 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72  ** the third par
c960: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
c970: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
c980: 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
c990: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
c9a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
c9b0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
c9c0: 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c  integer .** [SQL
c9d0: 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
c9e0: 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
c9f0: 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
ca00: 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
ca10: 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
ca20: 2e 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c 65  .  The available
ca30: 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 72   action codes ar
ca40: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50  e.** [SQLITE_COP
ca50: 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 73  Y | documented s
ca60: 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 65  eparately].  The
ca70: 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
ca80: 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ixth.** paramete
ca90: 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
caa0: 63 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20 74  ck are strings t
cab0: 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
cac0: 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
cad0: 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
cae0: 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
caf0: 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
cb00: 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
cb10: 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67 20   when preparing 
cb20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
cb30: 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
cb40: 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  .** source, to e
cb50: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
cb60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f  QL statements do
cb70: 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
cb80: 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20  ss data.** that 
cb90: 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
cba0: 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
cbb0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
cbc0: 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75   try to.** execu
cbd0: 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
cbe0: 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
cbf0: 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
cc00: 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
cc10: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cc20: 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
cc30: 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
cc40: 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
cc50: 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
cc60: 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
cc70: 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
cc80: 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
cc90: 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
cca0: 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
ccb0: 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
ccc0: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
ccd0: 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
cce0: 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
ccf0: 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
cd00: 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
cd10: 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
cd20: 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65 70  QL is being prep
cd30: 61 72 65 64 20 74 68 61 74 20 64 69 73 61 6c 6c  ared that disall
cd40: 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a 2a  ows everything.*
cd50: 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43 54 20  * except SELECT 
cd60: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a 2a  statements.  .**
cd70: 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** Only a singl
cd80: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
cd90: 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
cda0: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
cdb0: 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
cdc0: 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
cdd0: 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
cde0: 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
cdf0: 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
ce00: 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c 4c  us call.  A NULL
ce10: 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e   authorizer mean
ce20: 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72  s that no author
ce30: 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
ce40: 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
ce50: 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
ce60: 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
ce70: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
ce80: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
ce90: 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
cea0: 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20  ked only during 
ceb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
cec0: 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
ced0: 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
cee0: 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
cef0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
cf00: 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
cf10: 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
cf20: 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f 0a  te3_step()]..*/.
cf30: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
cf40: 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
cf50: 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
cf60: 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
cf70: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
cf80: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
cf90: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
cfa0: 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
cfb0: 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
cfc0: 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
cfd0: 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
cfe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
cff0: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
d000: 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
d010: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
d020: 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
d030: 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
d040: 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
d050: 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
d060: 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
d070: 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
d080: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
d090: 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
d0a0: 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
d0b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
d0c0: 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
d0d0: 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
d0e0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
d0f0: 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
d100: 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
d110: 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
d120: 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
d130: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
d140: 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
d150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
d160: 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
d170: 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
d180: 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
d190: 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
d1a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d1b0: 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
d1c0: 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
d1d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
d1e0: 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
d1f0: 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
d200: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
d210: 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
d220: 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
d230: 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53  orizer certain S
d240: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
d250: 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
d260: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
d270: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
d280: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
d290: 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
d2a0: 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
d2b0: 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
d2c0: 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
d2d0: 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
d2e0: 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
d2f0: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
d300: 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
d310: 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
d320: 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
d330: 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
d340: 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
d350: 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a  ation is to be .
d360: 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
d370: 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
d380: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
d390: 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e authorization 
d3a0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
d3b0: 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
d3c0: 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
d3d0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
d3e0: 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
d3f0: 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
d400: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
d410: 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
d420: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
d430: 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
d440: 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
d450: 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
d460: 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
d470: 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66  p", .** etc.) if
d480: 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68   applicable.  Th
d490: 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
d4a0: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
d4b0: 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
d4c0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d4d0: 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
d4e0: 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
d4f0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
d500: 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
d510: 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
d520: 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
d530: 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
d540: 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f  ctly from .** to
d550: 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
d560: 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
d570: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d590: 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
d5a0: 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
d5b0: 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
d5c0: 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
d5d0: 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
d5e0: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
d5f0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d610: 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
d620: 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
d630: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
d640: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d660: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
d670: 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
d680: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
d690: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d6b0: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
d6c0: 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
d6d0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
d6e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d700: 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
d710: 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
d720: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
d730: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
d740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
d750: 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
d760: 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
d770: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
d780: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
d7a0: 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
d7b0: 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
d7c0: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
d7d0: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
d7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
d7f0: 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
d800: 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
d810: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
d820: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
d830: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
d840: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
d850: 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
d860: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d870: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d880: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
d890: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
d8a0: 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
d8b0: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
d8c0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
d8d0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
d8e0: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
d8f0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
d900: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d910: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d920: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
d930: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
d940: 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
d950: 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
d960: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d970: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
d980: 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
d990: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
d9a0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d9b0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d9c0: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
d9d0: 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
d9e0: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
d9f0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
da00: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
da10: 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
da20: 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
da30: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
da40: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
da50: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
da60: 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
da70: 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
da80: 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
da90: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
daa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dab0: 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
dac0: 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
dad0: 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
dae0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
daf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
db00: 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
db10: 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
db20: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
db30: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
db40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
db50: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
db60: 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
db70: 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
db80: 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
db90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dba0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
dbb0: 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
dbc0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
dbd0: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
dbe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
dbf0: 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
dc00: 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
dc10: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
dc20: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
dc30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
dc40: 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
dc50: 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
dc60: 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
dc70: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
dc80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
dc90: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
dca0: 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
dcb0: 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
dcc0: 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
dcd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
dce0: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
dcf0: 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
dd00: 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
dd10: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
dd20: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
dd30: 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
dd40: 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
dd50: 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
dd60: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
dd70: 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
dd80: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
dd90: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
dda0: 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
ddb0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
ddc0: 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
ddd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
dde0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
ddf0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
de00: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
de10: 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
de20: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
de30: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
de40: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
de50: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
de60: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
de70: 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
de80: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
de90: 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
dea0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
deb0: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
dec0: 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
ded0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
dee0: 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
def0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
df00: 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
df10: 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
df20: 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
df30: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
df40: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
df50: 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
df60: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
df70: 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
df80: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
df90: 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
dfa0: 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
dfb0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
dfc0: 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
dfd0: 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
dfe0: 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
dff0: 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
e000: 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
e010: 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
e020: 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
e030: 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  ts..** The callb
e040: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
e050: 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
e060: 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
e070: 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 20  voked.** at the 
e080: 66 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f 73  first [sqlite3_s
e090: 74 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20 65  tep()] for the e
e0a0: 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 20  valuation of an 
e0b0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
e0c0: 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
e0d0: 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
e0e0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
e0f0: 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
e100: 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
e110: 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
e120: 73 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 65  shes and include
e130: 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s.** information
e140: 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   on how long tha
e150: 74 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e 2e  t statement ran.
e160: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e170: 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49  e3_profile() API
e180: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
e190: 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
e1a0: 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20  ental and.** is 
e1b0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
e1c0: 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
e1d0: 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
e1e0: 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
e1f0: 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
e200: 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
e210: 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
e220: 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
e230: 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
e240: 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
e250: 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
e260: 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
e270: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
e280: 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
e290: 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  backs.**.** This
e2a0: 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
e2b0: 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
e2c0: 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72  unction - the pr
e2d0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
e2e0: 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76  - that.** is inv
e2f0: 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
e300: 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
e310: 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
e320: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
e330: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
e340: 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
e350: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
e360: 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
e370: 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74  for this .** int
e380: 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
e390: 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
e3a0: 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
e3b0: 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uery..**.** The 
e3c0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
e3d0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
e3e0: 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
e3f0: 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70  rtual machine op
e400: 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20  codes,.** where 
e410: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
e420: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
e430: 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70   function. The p
e440: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
e450: 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64  .** itself is id
e460: 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
e470: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
e480: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
e490: 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61   The fourth.** a
e4a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
e4b0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f  function is a vo
e4c0: 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
e4d0: 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
e4e0: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  s callback.** fu
e4f0: 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65  nction each time
e500: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a   it is invoked..
e510: 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20  **.** If a call 
e520: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
e530: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
e540: 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  ep()], or [sqlit
e550: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
e560: 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65  ** results in fe
e570: 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64  wer than N opcod
e580: 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  es being execute
e590: 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  d, then the prog
e5a0: 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63  ress .** callbac
e5b0: 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b  k is never invok
e5c0: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20  ed..** .** Only 
e5d0: 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
e5e0: 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  s callback funct
e5f0: 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
e600: 74 65 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  tered for each.*
e610: 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  * open database 
e620: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65  connection.  Eve
e630: 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ry call to sqlit
e640: 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
e650: 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69  ler().** overwri
e660: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 73 20  tes the results 
e670: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
e680: 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f  call..** To remo
e690: 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ve the progress 
e6a0: 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74  callback altoget
e6b0: 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61  her, pass NULL a
e6c0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
e6d0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
e6e0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
e6f0: 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
e700: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
e710: 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20   a result other 
e720: 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65  than 0, then the
e730: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65   current .** que
e740: 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c  ry is immediatel
e750: 79 20 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64  y terminated and
e760: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 68   any database ch
e770: 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63  anges rolled bac
e780: 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69  k..** The contai
e790: 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ning [sqlite3_ex
e7a0: 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
e7b0: 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  step()], or.** [
e7c0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
e7d0: 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  e()] call return
e7e0: 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  s SQLITE_INTERRU
e7f0: 50 54 2e 20 20 20 54 68 69 73 20 66 65 61 74 75  PT.   This featu
e800: 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  re.** can be use
e810: 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
e820: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
e830: 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
e840: 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73   on a.** progres
e850: 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20  s dialog box in 
e860: 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73  a GUI..*/.void s
e870: 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
e880: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
e890: 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
e8a0: 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
e8b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
e8c0: 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
e8d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
e8e0: 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20  .**.** Open the 
e8f0: 73 71 6c 69 74 65 20 64 61 74 61 62 61 73 65 20  sqlite database 
e900: 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e  file "filename".
e910: 20 20 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22    The "filename"
e920: 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63   is UTF-8.** enc
e930: 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65  oded for [sqlite
e940: 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
e950: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
e960: 5d 20 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63  ] and UTF-16 enc
e970: 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  oded.** in the n
e980: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
e990: 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
e9a0: 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b  en16()]..** An [
e9b0: 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
e9c0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20   is returned in 
e9d0: 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69  *ppDb, even.** i
e9e0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
e9f0: 73 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  s. If the databa
ea00: 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 6f 72  se is opened (or
ea10: 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
ea20: 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20  sfully,.** then 
ea30: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
ea40: 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
ea50: 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
ea60: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68   is returned. Th
ea70: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
ea80: 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
ea90: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
eaa0: 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
eab0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
eac0: 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
ead0: 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
eae0: 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
eaf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
eb00: 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
eb10: 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
eb20: 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
eb30: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
eb40: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
eb50: 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c  en_v2()] is call
eb60: 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
eb70: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
eb80: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a  n16()] is used..
eb90: 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
eba0: 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
ebb0: 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
ebc0: 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
ebd0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
ebe0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
ebf0: 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  3*] handle shoul
ec00: 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
ec10: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a   passing it to.*
ec20: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  * [sqlite3_close
ec30: 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
ec40: 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
ec50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  d..**.** The [sq
ec60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
ec70: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
ec80: 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f   like [sqlite3_o
ec90: 70 65 6e 28 29 5d 20 65 78 63 65 70 74 20 74 68  pen()] except th
eca0: 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74  at.** provides t
ecb0: 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
ecc0: 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
ecd0: 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20  itional control 
ece0: 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20  over the.** new 
ecf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ed00: 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
ed10: 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
ed20: 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c   one of:.**.** <
ed30: 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ol>.** <li>  [SQ
ed40: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
ed50: 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  LY].** <li>  [SQ
ed60: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
ed70: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  ITE].** <li>  [S
ed80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
ed90: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
eda0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20  OPEN_CREATE].** 
edb0: 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ol>.**.** The 
edc0: 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e  first value open
edd0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72  s the database r
ede0: 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68  ead-only.  If th
edf0: 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a  e database does.
ee00: 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  ** not previousl
ee10: 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
ee20: 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
ee30: 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f  The second optio
ee40: 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64  n opens.** the d
ee50: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
ee60: 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
ee70: 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
ee80: 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a  reading only if.
ee90: 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ** if the file i
eea0: 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
eeb0: 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61  d.  In either ca
eec0: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
eed0: 6d 75 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20  must already.** 
eee0: 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f  exist or an erro
eef0: 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
ef00: 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e  The third option
ef10: 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
ef20: 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69  ase.** for readi
ef30: 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61  ng and writing a
ef40: 6e 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66  nd creates it if
ef50: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
ef60: 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54  eady exist..** T
ef70: 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73  he third options
ef80: 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61   is behavior tha
ef90: 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
efa0: 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
efb0: 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  en()].** and [sq
efc0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
efd0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
efe0: 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
eff0: 72 79 3a 22 20 6f 72 20 61 6e 20 65 6d 70 74 79  ry:" or an empty
f000: 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 6e   string, then an
f010: 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d   private.** in-m
f020: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
f030: 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
f040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
f050: 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  his in-memory.**
f060: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
f070: 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64  anish when the d
f080: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f090: 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
f0a0: 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
f0b0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
f0c0: 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
f0d0: 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
f0e0: 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61  filenames.** tha
f0f0: 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
f100: 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20   ":" character. 
f110: 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
f120: 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e  ed that .** when
f130: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
f140: 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73  name really does
f150: 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22   begin with.** "
f160: 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66  :" that you pref
f170: 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
f180: 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
f190: 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20  like "./" to.** 
f1a0: 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
f1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
f1c0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
f1d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
f1e0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
f1f0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
f200: 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
f210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
f220: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a  rating system .*
f230: 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  * interface that
f240: 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
f250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
f260: 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65  uld use.  If the
f270: 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
f280: 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70  eter is a NULL p
f290: 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
f2a0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
f2b0: 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  _vfs].** object 
f2c0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
f2d0: 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77  b>Note to window
f2e0: 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
f2f0: 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
f300: 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
f310: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
f320: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f330: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
f340: 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65  en_v2()] must be
f350: 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
f360: 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
f370: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
f380: 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
f390: 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
f3a0: 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
f3b0: 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
f3c0: 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
f3d0: 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
f3e0: 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
f3f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
f400: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
f410: 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  pen_v2()]..*/.in
f420: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
f430: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
f440: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
f450: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
f460: 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
f470: 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
f480: 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
f490: 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
f4a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
f4b0: 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
f4c0: 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
f4d0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
f4e0: 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
f4f0: 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
f500: 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
f510: 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
f520: 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
f530: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
f540: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
f550: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
f560: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
f570: 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
f580: 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
f590: 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
f5a0: 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
f5b0: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
f5c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
f5d0: 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
f5e0: 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
f5f0: 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
f600: 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
f610: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f620: 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
f630: 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
f640: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
f650: 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
f660: 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
f670: 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  umeric.** [SQLIT
f680: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
f690: 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
f6a0: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
f6b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
f6c0: 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73  ].** for the mos
f6d0: 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
f6e0: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
f6f0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
f700: 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20   with [sqlite3] 
f710: 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 20 49 66  handle 'db'.  If
f720: 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
f730: 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65  l failed but the
f740: 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
f750: 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
f760: 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
f770: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
f780: 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  3_errcode().** i
f790: 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a  s undefined. .**
f7a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f7b0: 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
f7c0: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
f7d0: 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
f7e0: 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65 78 74 20  angauge.** text 
f7f0: 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
f800: 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
f810: 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31  her UTF8 or UTF1
f820: 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
f830: 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
f840: 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
f850: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
f860: 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
f870: 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e  .  The .** strin
f880: 67 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69  g may be overwri
f890: 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
f8a0: 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65 6e  ted by subsequen
f8b0: 74 20 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74  t calls to SQLit
f8c0: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
f8d0: 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
f8e0: 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71  Calls to many sq
f8f0: 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e  lite3_* function
f900: 73 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20  s set the error 
f910: 63 6f 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20  code and string 
f920: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
f930: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
f940: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
f950: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
f960: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
f970: 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74 69 6e 67  .** (overwriting
f980: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 76 61   the previous va
f990: 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74 68 61 74  lues). Note that
f9a0: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
f9b0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a  e3_errcode()],.*
f9c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
f9d0: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
f9e0: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74  e3_errmsg16()] t
f9f0: 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
fa00: 20 61 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72   affect the.** r
fa10: 65 73 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65  esults of future
fa20: 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43   invocations.  C
fa30: 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74  alls to API rout
fa40: 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  ines that do not
fa50: 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72   return.** an er
fa60: 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c  ror code (exampl
fa70: 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  e: [sqlite3_data
fa80: 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f  _count()]) do no
fa90: 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  t.** change the 
faa0: 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72  error code retur
fab0: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
fac0: 69 6e 65 2e 20 20 49 6e 74 65 72 66 61 63 65 73  ine.  Interfaces
fad0: 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 6e 6f 74   that are.** not
fae0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
faf0: 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
fb00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
fb10: 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 5b 73  (examples:.** [s
fb20: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
fb30: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
fb40: 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
fb50: 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63 68 61 6e  e()] do not chan
fb60: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
fb70: 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 41   code.  .**.** A
fb80: 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72  ssuming no other
fb90: 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c   intervening sql
fba0: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73  ite3_* API calls
fbb0: 20 61 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65   are made, the e
fbc0: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74  rror.** code ret
fbd0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
fbe0: 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  nction is associ
fbf0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
fc00: 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74  me error as.** t
fc10: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
fc20: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
fc30: 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
fc40: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
fc50: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
fc60: 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
fc70: 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
fc80: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
fc90: 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
fca0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
fcb0: 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
fcc0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
fcd0: 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
fce0: 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
fcf0: 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** Instance of t
fd00: 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
fd10: 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20  sent single SQL 
fd20: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69  statements.  Thi
fd30: 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c  s.** is variousl
fd40: 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
fd50: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
fd60: 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70  " or a .** "comp
fd70: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
fd80: 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
fd90: 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
fda0: 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  ** .** The life 
fdb0: 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
fdc0: 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
fdd0: 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
fde0: 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
fdf0: 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
fe00: 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
fe10: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
fe20: 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
fe30: 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
fe40: 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
fe50: 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
fe60: 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a  ameters using.**
fe70: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
fe80: 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
fe90: 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66  e3_bind_* interf
fea0: 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  aces]..** <li> R
feb0: 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
fec0: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
fed0: 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
fee0: 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
fef0: 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
ff00: 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
ff10: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
ff20: 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
ff30: 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
ff40: 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
ff50: 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
ff60: 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
ff70: 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
ff80: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
ff90: 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
ffa0: 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
ffb0: 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
ffc0: 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
ffd0: 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
ffe0: 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
fff0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
10000 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
10010 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
10020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10030 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
10040 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
10050 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
10060 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
10070 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
10080 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
10090 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
100a0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
100b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a  ese routines. .*
100c0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
100d0 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20  rgument "db" is 
100e0 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51  an [sqlite3 | SQ
100f0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 68 61  Lite database ha
10100 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e  ndle] .** obtain
10110 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20  ed from a prior 
10120 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
10130 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
10140 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
10150 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
10160 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
10170 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
10180 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
10190 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
101a0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
101b0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
101c0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
101d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
101e0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
101f0 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
10200 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
10210 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
10220 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
10230 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
10240 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
10250 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
10260 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f  ess.** than zero
10270 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
10280 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
10290 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
102a0 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79 74  tor.  If.** nByt
102b0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
102c0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
102d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
102e0 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65   of .** bytes re
102f0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
10300 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
10310 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
10320 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
10330 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
10340 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 63 68   first '\000' ch
10350 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75  aracter or .** u
10360 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74  ntil the nByte-t
10370 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
10380 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
10390 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
103a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
103b0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
103c0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
103d0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51 4c  the first.** SQL
103e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
103f0 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ql.  This routin
10400 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20  e only compiles 
10410 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
10420 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20  ent.** in zSql, 
10430 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
10440 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
10450 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
10460 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
10470 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
10480 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
10490 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  iled .** [sqlite
104a0 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61  3_stmt | SQL sta
104b0 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72 65  tement structure
104c0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
104d0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
104e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
104f0 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69  .  Or if there i
10500 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
10510 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65  tmt may be.** se
10520 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  t to NULL.  If t
10530 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
10540 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20 28  ntained no SQL (
10550 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
10560 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74 72  and.** empty str
10570 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
10580 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
10590 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20  s set to NULL.  
105a0 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 70  The calling.** p
105b0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
105c0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
105d0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
105e0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
105f0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
10600 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
10610 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
10620 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
10630 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
10640 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
10650 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
10660 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  se an .** [SQLIT
10670 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
10680 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
10690 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
106a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
106b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
106c0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
106d0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
106e0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
106f0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
10700 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
10710 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
10720 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
10730 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
10740 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
10750 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
10760 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
10770 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
10780 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
10790 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
107a0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
107b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
107c0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
107d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a  a copy of the .*
107e0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
107f0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
10800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
10810 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
10820 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
10830 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
10840 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
10850 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
10860 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
10870 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
10880 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
10890 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
108a0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
108b0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
108c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
108d0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
108e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
108f0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
10900 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
10910 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
10920 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
10930 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a 2a  anged in a way.*
10940 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  * that makes the
10950 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
10960 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
10970 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
10980 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
10990 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
109a0 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
109b0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
109c0 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
109d0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
109e0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
109f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
10a00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
10a10 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
10a20 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
10a30 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
10a40 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
10a50 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
10a60 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 61 72   text of the par
10a70 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74 68  sing.** error th
10a80 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
10a90 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
10aa0 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
10ab0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
10ac0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
10ad0 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74  curs, .** [sqlit
10ae0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
10af0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
10b00 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b  e detailed .** [
10b10 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
10b20 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
10b30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
10b40 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
10b50 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 73   result codes] s
10b60 75 63 68 20 61 73 20 64 69 72 65 63 74 6c 79 2e  uch as directly.
10b70 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62  .** The legacy b
10b80 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
10b90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10ba0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
10bb0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a  urn a generic.**
10bc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10bd0 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20  result code and 
10be0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
10bf0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
10c00 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
10c10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
10c20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
10c30 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
10c40 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
10c50 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  m..** With the "
10c60 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65  v2" prepare inte
10c70 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
10c80 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
10c90 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a  r the error is.*
10ca0 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  * returned immed
10cb0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
10cc0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
10cd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
10ce0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
10cf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
10d00 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
10d10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
10d20 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
10d30 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
10d40 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
10d50 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
10d60 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10d70 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
10d80 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
10d90 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
10da0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
10db0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
10dc0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
10dd0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
10de0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
10df0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
10e00 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
10e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
10e20 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
10e30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
10e40 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
10e50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
10e60 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
10e70 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
10e80 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
10e90 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
10ea0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
10eb0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
10ec0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
10ed0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
10ee0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
10ef0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
10f00 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
10f10 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
10f20 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
10f30 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
10f40 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
10f50 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
10f60 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
10f70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
10f80 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
10f90 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
10fa0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
10fb0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
10fc0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
10fd0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
10fe0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
10ff0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
11000 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
11010 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
11020 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
11030 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
11040 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
11050 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
11060 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
11070 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
11080 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
11090 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
110a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
110b0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
110c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
110d0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
110e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
110f0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
11100 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
11110 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
11120 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
11130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11140 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
11150 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
11160 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
11170 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
11180 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
11190 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
111a0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
111b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
111c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
111d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
111e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
111f0 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c  3REF:  Dynamical
11200 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
11210 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  bject.**.** SQLi
11220 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
11230 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76  typing for the v
11240 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
11250 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a 2a    Values can .**
11260 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
11270 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
11280 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
11290 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20 57  OBs, or NULL.  W
112a0 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20 61  hen.** passing a
112b0 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e 74  round values int
112c0 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76 61  ernally, each va
112d0 6c 75 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  lue is represent
112e0 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73 74  ed as.** an inst
112f0 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
11300 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
11310 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11320 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
11330 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
11340 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e  PI3REF:  SQL Fun
11350 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
11360 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
11370 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
11380 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
11390 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
113a0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
113b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
113c0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
113d0 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63 74  o such an object
113e0 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   is the.** first
113f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75 73   parameter to us
11400 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  er-defined SQL f
11410 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70  unctions..*/.typ
11420 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
11430 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
11440 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
11450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42  .** CAPI3REF:  B
11460 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
11470 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
11480 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ents.**.** In th
11490 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
114a0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
114b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
114c0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
114d0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c  ** one or more l
114e0 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72  iterals can be r
114f0 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61  eplace by a para
11500 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20  meter in one of 
11510 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a 0a  these.** forms:.
11520 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
11530 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
11540 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41  NNN.** <li>  :AA
11550 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a  A.** <li>  @AAA.
11560 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
11570 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
11580 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
11590 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
115a0 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
115b0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41  r literal,.** AA
115c0 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  A is an alphanum
115d0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20  eric identifier 
115e0 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72  and VVV is a var
115f0 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72  iable name accor
11600 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ding.** to the s
11610 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74  yntax rules of t
11620 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69  he TCL programmi
11630 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a 20  ng language..** 
11640 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
11650 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28  ese parameters (
11660 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
11670 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
11680 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
11690 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
116a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
116b0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
116c0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
116d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
116e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
116f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c  _*() routines al
11700 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74 65  ways is a pointe
11710 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
11720 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
11730 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  t returned from 
11740 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11750 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74 73  _v2()] or.** its
11760 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65 20   variants.  The 
11770 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
11780 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
11790 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
117a0 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68 65   to be set.  The
117b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
117c0 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65 78   has.** an index
117d0 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65 20   of 1. When the 
117e0 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61 6d  same named param
117f0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
11800 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
11810 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  ond.** and subse
11820 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
11830 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
11840 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
11850 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
11860 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72  .  The index for
11870 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  .** named parame
11880 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
11890 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
118a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
118b0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
118c0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
118d0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f  d.  The index fo
118e0 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72 61  r "?NNN".** para
118f0 6d 65 74 65 73 20 69 73 20 74 68 65 20 76 61 6c  metes is the val
11900 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
11910 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
11920 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
11930 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
11940 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  me.** parameter 
11950 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
11960 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61  BLE_NUMBER (defa
11970 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
11980 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d  .** See <a href=
11990 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69  "limits.html">li
119a0 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f  mits.html</a> fo
119b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
119c0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
119d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
119e0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
119f0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
11a00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
11a10 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74  In those.** rout
11a20 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
11a30 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
11a40 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
11a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
11a60 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72  es.** in the par
11a70 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
11a80 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
11a90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11aa0 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a 2a   bytes in the.**
11ab0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
11ac0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
11ad0 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d 62  cters.  The numb
11ae0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64  er.** of bytes d
11af0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
11b00 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
11b10 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f  tor at the end o
11b20 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  f strings..** If
11b30 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
11b40 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
11b50 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
11b60 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
11b70 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
11b80 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
11b90 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
11ba0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  r..**.** The fif
11bb0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
11bc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
11bd0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
11be0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
11bf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
11c00 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
11c10 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
11c20 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
11c30 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74  B or.** text aft
11c40 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
11c50 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
11c60 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
11c70 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
11c80 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
11c90 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
11ca0 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79  then the library
11cb0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
11cc0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  e information.**
11cd0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
11ce0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
11cf0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
11d00 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20 49   to be freed.  I
11d10 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20 61  f the.** fifth a
11d20 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
11d30 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
11d40 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20 53  ANSIENT], then S
11d50 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 0a  QLite makes its.
11d60 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ** own private c
11d70 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
11d80 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
11d90 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ore the sqlite3_
11da0 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75 74  bind_*().** rout
11db0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
11dc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
11dd0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
11de0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
11df0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e 20  LOB of length n 
11e00 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
11e10 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  d with zeros.  A
11e20 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
11e30 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
11e40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
11e50 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
11e60 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69  old it size) whi
11e70 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
11e80 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
11e90 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
11ea0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
11eb0 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
11ec0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
11ed0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
11ee0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
11ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
11f00 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
11f10 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
11f20 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
11f30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
11f40 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
11f50 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
11f60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
11f70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
11f80 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
11f90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
11fa0 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
11fb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11fc0 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
11fd0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
11fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
11ff0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
12000 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
12010 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
12020 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
12030 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
12040 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
12050 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
12060 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
12070 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
12080 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
12090 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
120a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
120b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
120c0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
120d0 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
120e0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
120f0 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73   if malloc fails
12100 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ..** [SQLITE_MIS
12110 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USE] is returned
12120 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
12130 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
12140 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61   a virtual.** ma
12150 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
12160 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
12170 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
12180 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
12190 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
121a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
121b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
121c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
121d0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
121e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
121f0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
12200 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
12210 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
12220 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
12230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12240 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
12250 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
12260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12270 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
12280 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
12290 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
122a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
122b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
122c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
122d0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
122e0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
122f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
12300 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
12310 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
12320 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
12330 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
12340 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
12350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
12360 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
12370 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
12380 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
12390 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
123a0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
123b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
123c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
123d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
123e0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73 0a  Host Parameters.
123f0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
12400 20 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70 61   largest host pa
12410 72 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69 6e  rameter index in
12420 20 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64   the precompiled
12430 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e   statement given
12440 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75 6d  .** as the argum
12450 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20 68  ent.  When the h
12460 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 61  ost parameters a
12470 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20  re of the forms 
12480 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20 6f  like ":AAA".** o
12490 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65 79  r "?", then they
124a0 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65   are assigned se
124b0 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73  quential increas
124c0 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69  ing numbers begi
124d0 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e  nning.** with on
124e0 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20  e, so the value 
124f0 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
12500 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
12510 74 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a 2a  ters.  However.*
12520 2a 20 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f  * if the same ho
12530 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
12540 65 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70  e is used multip
12550 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f  le times, each o
12560 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20  ccurrance.** is 
12570 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  given the same n
12580 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61  umber, so the va
12590 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
125a0 74 68 61 74 20 63 61 73 65 20 69 73 20 74 68 65  that case is the
125b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e   number.** of un
125c0 69 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65  ique host parame
125d0 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20 68  ter names.  If h
125e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ost parameters o
125f0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
12600 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28 77  ".** are used (w
12610 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  here NNN is an i
12620 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68 65  nteger) then the
12630 72 65 20 6d 69 67 68 74 20 62 65 20 67 61 70 73  re might be gaps
12640 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   in the.** numbe
12650 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61 6c  ring and the val
12660 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
12670 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
12680 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
12690 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d 65  e.** host parame
126a0 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61 72  ter with the lar
126b0 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75 65  gest index value
126c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 70  ..**.** The prep
126d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d  ared statement m
126e0 75 73 74 20 6e 6f 74 20 62 65 20 5b 73 71 6c 69  ust not be [sqli
126f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
12700 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20 70 72 69  inalized].** pri
12710 6f 72 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  or to this routi
12720 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67 2e 20 20  ne returnning.  
12730 4f 74 68 65 72 77 69 73 65 20 74 68 65 20 72 65  Otherwise the re
12740 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
12750 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72 6f 62 61  ned.** and proba
12760 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
12770 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12780 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
12790 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
127a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
127b0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
127c0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
127d0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
127e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
127f0 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
12800 6f 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  of the n-th para
12810 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a 2a 20 5b  meter in a .** [
12820 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
12830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12840 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61  t]..** Host para
12850 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
12860 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  rm ":AAA" or "@A
12870 41 41 22 20 6f 72 20 22 24 56 56 56 22 20 68 61  AA" or "$VVV" ha
12880 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69  ve a name.** whi
12890 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
128a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
128b0 22 20 6f 72 20 22 24 56 56 56 22 2e 20 20 0a 2a  " or "$VVV".  .*
128c0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
128d0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
128e0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 0a  " or "$" or "@".
128f0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
12900 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
12910 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  me..** Parameter
12920 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
12930 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 76 65  " or "?NNN" have
12940 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20   no name..**.** 
12950 54 68 65 20 66 69 72 73 74 20 62 6f 75 6e 64 20  The first bound 
12960 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
12970 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
12980 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
12990 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20   value n is out 
129a0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
129b0 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65  he n-th paramete
129c0 72 20 69 73 20 6e 61 6d 65 6c 65 73 73 2c 0a 2a  r is nameless,.*
129d0 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  * then NULL is r
129e0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65  eturned.  The re
129f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
12a00 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 0a 2a   always in the.*
12a10 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  * UTF-8 encoding
12a20 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
12a30 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
12a40 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
12a50 69 66 69 65 64 0a 2a 2a 20 61 73 20 55 54 46 2d  ified.** as UTF-
12a60 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
12a70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 20 5b  repare16()] or [
12a80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
12a90 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
12aa0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
12ab0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
12ac0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
12ad0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
12ae0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
12af0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
12b00 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
12b10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
12b20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
12b30 69 6e 64 65 78 20 6f 66 20 61 20 68 6f 73 74 20  index of a host 
12b40 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74  parameter with t
12b50 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 2e 0a 2a  he given name..*
12b60 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20  * The name must 
12b70 6d 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20  match exactly.  
12b80 49 66 20 6e 6f 20 70 61 72 61 6d 65 74 65 72 20  If no parameter 
12b90 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
12ba0 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f 75 6e 64  ame is .** found
12bb0 2c 20 72 65 74 75 72 6e 20 30 2e 20 20 50 61 72  , return 0.  Par
12bc0 61 6d 65 74 65 72 20 6e 61 6d 65 73 20 6d 75 73  ameter names mus
12bd0 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f 0a 69 6e  t be UTF8..*/.in
12be0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
12bf0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
12c00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
12c10 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
12c20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12c30 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
12c40 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
12c50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
12c60 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
12c70 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
12c80 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
12c90 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
12ca0 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
12cb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
12cc0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
12cd0 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   a .** [sqlite3_
12ce0 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
12cf0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65  statement].  Use
12d00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
12d10 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f  .** reset all ho
12d20 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
12d30 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
12d40 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
12d50 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
12d60 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
12d70 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
12d80 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
12d90 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 52 65  ult Set.**.** Re
12da0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
12db0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
12dc0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
12dd0 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  urned by the .**
12de0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
12df0 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
12e00 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72  atement]. This r
12e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
12e20 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20  .** if pStmt is 
12e30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
12e40 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
12e50 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
12e60 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55  .** example an U
12e70 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e 74 20 73  PDATE)..*/.int s
12e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
12e90 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
12ea0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
12eb0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
12ec0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
12ed0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 54 68  ult Set.**.** Th
12ee0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
12ef0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
12f00 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
12f10 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
12f20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
12f30 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
12f40 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
12f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
12f60 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
12f70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
12f80 65 72 20 74 6f 20 61 20 55 54 46 38 20 73 74 72  er to a UTF8 str
12f90 69 6e 67 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ing and sqlite3_
12fa0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
12fb0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
12fc0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 31 36 20  nter to a UTF16 
12fd0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
12fe0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
12ff0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13000 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
13010 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
13020 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53  implements the S
13030 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
13040 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
13050 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
13060 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
13070 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
13080 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  lumn is.** numbe
13090 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
130a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
130b0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
130c0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
130d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
130e0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
130f0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
13100 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
13110 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
13120 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
13130 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  xt call sqlite3_
13140 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
13150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
13160 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74  name16().** on t
13170 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
13180 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
13190 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
131a0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
131b0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
131c0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
131d0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
131e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
131f0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
13200 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
13210 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
13220 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  rned..*/.const c
13230 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
13240 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
13250 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
13260 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
13270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
13280 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
13290 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
132a0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
132b0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
132c0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
132d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
132e0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
132f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
13300 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
13310 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
13320 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
13330 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54  sult of a SELECT
13340 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
13350 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
13360 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
13370 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
13380 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
13390 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
133a0 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46  er a UTF8 or UTF
133b0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
133c0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
133d0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
133e0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
133f0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
13400 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
13410 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
13420 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
13430 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13440 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
13450 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
13460 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
13470 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73   until.** the [s
13480 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
13490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
134a0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
134b0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
134c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
134d0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
134e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
134f0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
13500 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
13510 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
13520 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
13530 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
13540 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
13550 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
13560 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
13570 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
13580 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13590 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
135a0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
135b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
135c0 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
135d0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  L statement]..**
135e0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
135f0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
13600 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
13610 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
13620 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
13630 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
13640 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
13650 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
13660 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
13670 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
13680 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
13690 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
136a0 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
136b0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
136c0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
136d0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
136e0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
136f0 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77  urn NULL. Otherw
13700 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
13710 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66   the .** name of
13720 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
13730 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e  tabase, table an
13740 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
13750 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ery result.** co
13760 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
13770 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
13780 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
13790 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
137a0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
137b0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 20 55  th "16" return U
137c0 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64  TF-16.** encoded
137d0 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
137e0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
137f0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
13800 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
13810 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
13820 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
13830 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
13840 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
13850 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
13860 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
13870 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
13880 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
13890 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
138a0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
138b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
138c0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
138d0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
138e0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
138f0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
13900 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
13910 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
13920 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
13930 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
13940 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
13950 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
13960 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
13970 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
13980 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
13990 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
139a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
139b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
139c0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
139d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
139e0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
139f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
13a00 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
13a10 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
13a20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
13a30 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
13a40 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
13a50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
13a60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
13a70 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
13a80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
13a90 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
13aa0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
13ab0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
13ac0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
13ad0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
13ae0 6d 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69  meter is a [sqli
13af0 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
13b00 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
13b10 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20  t]. .** If this 
13b20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53  statement is a S
13b30 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
13b40 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
13b50 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65  mn of the .** re
13b60 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
13b70 74 20 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43  t  of that SELEC
13b80 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  T is a table col
13b90 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
13ba0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
13bb0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
13bc0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
13bd0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
13be0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
13bf0 2e 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  . If the Nth col
13c00 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
13c10 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
13c20 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
13c30 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
13c40 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
13c50 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
13c60 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
13c70 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
13c80 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65 78 61 6d  ncoded. For exam
13c90 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64  ple, in.** the d
13ca0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
13cb0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
13cc0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
13cd0 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65  );.**.** And the
13ce0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
13cf0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  ment compiled:.*
13d00 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
13d10 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
13d20 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73 20  **.** Then this 
13d30 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
13d40 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
13d50 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
13d60 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75  e second.** resu
13d70 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  lt column (i==1)
13d80 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
13d90 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
13da0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
13db0 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  .** (i==0)..**.*
13dc0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
13dd0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
13de0 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
13df0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
13e00 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
13e10 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
13e20 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
13e30 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
13e40 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
13e50 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
13e60 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
13e70 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
13e80 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
13e90 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
13ea0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
13eb0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
13ec0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
13ed0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
13ee0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
13ef0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
13f00 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
13f10 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
13f20 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
13f30 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
13f40 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
13f50 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69  e3_stmt *, int i
13f60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
13f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
13f80 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
13f90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
13fa0 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20   .** CAPI3REF:  
13fb0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
13fc0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
13fd0 41 66 74 65 72 20 61 6e 20 5b 73 71 6c 69 74 65  After an [sqlite
13fe0 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61  3_stmt | SQL sta
13ff0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
14000 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61   prepared with a
14010 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68   call.** to eith
14020 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
14030 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
14040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
14050 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20  v2()] or to one 
14060 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  of.** the legacy
14070 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
14080 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
14090 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
140a0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65  are16()],.** the
140b0 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
140c0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
140d0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
140e0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
140f0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a   .** statement..
14100 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
14110 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
14120 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65  r of this sqlite
14130 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
14140 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
14150 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
14160 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
14170 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
14180 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
14190 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
141a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
141b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
141c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
141d0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
141e0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
141f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
14200 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
14210 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
14220 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
14230 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
14240 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
14250 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
14260 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
14270 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
14280 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
14290 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
142a0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63  .** In the lagac
142b0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
142c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
142d0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
142e0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20  LITE_BUSY], .** 
142f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
14300 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
14310 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
14320 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
14330 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
14340 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
14350 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53   of the other [S
14360 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
14370 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53  t code].** or [S
14380 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
14390 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
143a0 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62  lt code] might b
143b0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
143c0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
143d0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
143e0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
143f0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
14400 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
14410 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
14420 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
14430 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
14440 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
14450 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
14460 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
14470 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
14480 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
14490 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
144a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
144b0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
144c0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
144d0 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
144e0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
144f0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
14500 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
14510 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
14520 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
14530 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
14540 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
14550 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
14560 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
14570 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
14580 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
14590 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
145a0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
145b0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
145c0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
145d0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
145e0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
145f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
14600 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
14610 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
14620 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
14630 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
14640 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
14650 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
14660 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
14670 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a  ny data, then .*
14680 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69  * [SQLITE_ROW] i
14690 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
146a0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
146b0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a  f data is ready.
146c0 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  ** for processin
146d0 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  g by the caller.
146e0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
146f0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
14700 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
14710 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63  3_column_int | c
14720 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
14730 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
14740 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
14750 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
14760 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
14770 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20  row of data..** 
14780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14790 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
147a0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
147b0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
147c0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
147d0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
147e0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
147f0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
14800 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
14810 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
14820 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
14830 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
14840 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
14850 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
14860 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
14870 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
14880 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
14890 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51  (example:.** [SQ
148a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
148b0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
148c0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
148d0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
148e0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
148f0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
14900 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
14910 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  ] on the.** [sql
14920 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
14930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
14940 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
14950 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
14960 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
14970 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
14980 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
14990 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
149a0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
149b0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
149c0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
149d0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
149e0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
149f0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
14a00 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 73 71   called on a [sq
14a10 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
14a20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14a30 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
14a40 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
14a50 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
14a60 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
14a70 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
14a80 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
14a90 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
14aa0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
14ab0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
14ac0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
14ad0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
14ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14af0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
14b00 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
14b10 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
14b20 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
14b30 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
14b40 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
14b50 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
14b60 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
14b70 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
14b80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
14b90 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
14ba0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
14bb0 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
14bc0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
14bd0 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
14be0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
14bf0 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
14c00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
14c10 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
14c20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
14c30 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
14c40 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
14c50 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
14c60 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
14c70 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
14c80 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
14c90 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
14ca0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
14cb0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
14cc0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
14cd0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
14ce0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
14cf0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
14d00 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
14d10 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
14d20 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
14d30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
14d40 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
14d50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14d60 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
14d70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
14d80 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
14d90 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
14da0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
14db0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
14dc0 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
14dd0 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
14de0 66 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  fic [SQLITE_ERRO
14df0 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
14e00 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
14e10 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
14e20 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
14e30 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
14e40 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
14e50 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
14e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
14e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
14e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14e90 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  :.**.** Return t
14ea0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
14eb0 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
14ec0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
14ed0 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
14ee0 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
14ef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14f00 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53   that returns [S
14f10 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 69 73  QLITE_ROW], this
14f20 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 6c 6c   routine.** will
14f30 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
14f40 20 76 61 6c 75 65 20 61 73 20 74 68 65 20 5b 73   value as the [s
14f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
14f60 75 6e 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e  unt()] function.
14f70 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74  .** After [sqlit
14f80 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
14f90 65 74 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49  eturned an [SQLI
14fa0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
14fb0 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61  E_BUSY], or.** a
14fc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
14fd0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72   error code], or
14fe0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
14ff0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
15000 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20  n .** called on 
15010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
15020 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
15030 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
15040 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74  first time,.** t
15050 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
15060 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
15070 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
15080 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
15090 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
150a0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
150b0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
150c0 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 76 61 6c  .**.** Every val
150d0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
150e0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
150f0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
15100 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
15110 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
15120 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
15130 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
15140 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
15150 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
15160 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
15170 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
15180 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
15190 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
151a0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
151b0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
151c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
151d0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
151e0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
151f0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
15200 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
15210 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
15220 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
15230 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
15240 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
15250 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
15260 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
15270 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
15280 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
15290 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
152a0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
152b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
152c0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
152d0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
152e0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
152f0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
15300 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
15310 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
15320 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
15330 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
15340 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
15350 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
15360 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
15370 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
15380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15390 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
153a0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 0a  From A Query.**.
153b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
153c0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
153d0 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20  tion about.** a 
153e0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
153f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
15400 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
15410 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a  ry.  In every.**
15420 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
15430 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
15440 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  inter to the .**
15450 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
15460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
15470 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a  that is being.**
15480 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
15490 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
154a0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
154b0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
154c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
154d0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
154e0 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a  variants) and.**
154f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15500 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
15510 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
15520 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
15530 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64  ation .** should
15540 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
15550 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
15560 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
15570 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20  t set.** has an 
15580 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a  index of 0..**.*
15590 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
155a0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75  tement is not cu
155b0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
155c0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
155d0 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63   if the.** the c
155e0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
155f0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
15600 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
15610 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20  ined. .** These 
15620 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
15630 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
15640 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15650 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15660 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
15670 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
15680 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
15690 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
156a0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
156b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
156c0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73   has been call s
156d0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
156e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
156f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
15700 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
15710 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
15720 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
15730 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
15740 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15750 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
15760 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
15770 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
15780 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
15790 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
157a0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
157b0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
157c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
157d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
157e0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
157f0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
15800 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
15810 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
15820 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
15830 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
15840 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
15850 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ned.  .**.** The
15860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15870 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
15880 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
15890 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
158a0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
158b0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
158c0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
158d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
158e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
158f0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
15900 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
15910 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
15920 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
15930 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
15940 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
15950 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
15960 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
15980 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
15990 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
159a0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
159b0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
159c0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
159d0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
159e0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
159f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15a00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
15a10 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
15a20 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
15a30 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
15a40 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
15a50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
15a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15a70 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
15a80 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
15a90 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
15aa0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
15ab0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
15ac0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
15ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
15ae0 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65  es() .** routine
15af0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
15b00 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
15b10 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
15b20 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
15b30 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
15b40 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
15b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
15b60 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
15b70 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
15b80 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
15b90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
15ba0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
15bb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
15bc0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
15bd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
15be0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
15bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
15c00 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
15c10 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
15c20 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
15c30 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
15c40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
15c50 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
15c60 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
15c70 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
15c80 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
15c90 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
15ca0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
15cb0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
15cc0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
15cd0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
15ce0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15cf0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
15d00 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
15d10 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15d20 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
15d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
15d40 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
15d50 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
15d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
15d70 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
15d80 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
15d90 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64 20 6f  UTF-16 instead o
15da0 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68  f UTF-8.  .** Th
15db0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15dc0 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  r is not include
15dd0 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e  d in this count.
15de0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
15df0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
15e00 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
15e10 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
15e20 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
15e30 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
15e40 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
15e50 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
15e60 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
15e70 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
15e80 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
15e90 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
15ea0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20  nternally to do 
15eb0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a  the conversion.*
15ec0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  * automatically.
15ed0 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
15ee0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
15ef0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68  e conversions th
15f00 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69 65  at.** are applie
15f10 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
15f20 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
15f30 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
15f40 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
15f50 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
15f60 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
15f70 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
15f80 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
15f90 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
15fa0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
15fb0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
15fc0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
15fd0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
15fe0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
15ff0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
16000 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
16010 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
16020 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
16030 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
16040 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
16050 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
16060 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
16070 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
16080 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
16090 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
160a0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
160b0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
160c0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
160d0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
160e0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
160f0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
16100 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
16110 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
16120 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
16130 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58  for INTEGER->TEX
16140 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
16150 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
16160 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
16170 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
16180 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
16190 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
161a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
161b0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
161c0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
161d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
161e0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
161f0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
16200 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
16210 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
16220 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
16230 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
16240 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
16250 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
16260 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
16270 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
16280 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
16290 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
162a0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
162b0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
162c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
162d0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
162e0 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
162f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
16300 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
16310 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
16320 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
16330 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
16340 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
16350 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
16360 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
16370 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
16380 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
16390 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
163a0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
163b0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
163c0 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
163d0 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
163e0 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
163f0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
16400 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
16410 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
16420 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
16430 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61  its.** on equava
16440 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
16450 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
16460 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
16470 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
16480 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
16490 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
164a0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
164b0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
164c0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
164d0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
164e0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
164f0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
16500 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
16510 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
16520 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
16530 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
16540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16550 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
16560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16570 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
16580 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79  alidated. .** Ty
16590 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
165a0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
165b0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
165c0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
165d0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
165e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
165f0 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
16600 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
16610 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
16620 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a  _column_text() .
16630 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73  **          or s
16640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16650 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
16660 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
16670 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
16680 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62         need to b
16690 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
166a0 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  tring.</p></li>.
166b0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  **.** <li><p>  T
166c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
166d0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
166e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
166f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
16700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
16710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
16720 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
16730 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
16740 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
16750 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54  *          to UT
16760 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  F-16.</p></li>.*
16770 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
16780 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
16790 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
167a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
167b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
167c0 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
167d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
167e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
167f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
16800 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
16810 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e         to UTF-8.
16820 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  </p></li>.** </u
16830 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
16840 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
16850 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
16860 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
16870 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
16880 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
16890 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
168a0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
168b0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
168c0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
168d0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
168e0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
168f0 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
16900 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
16910 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
16920 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
16930 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
16940 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
16950 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20  e, but sometime 
16960 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
16970 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
16980 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
16990 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
169a0 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  lidated.  .**.**
169b0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
169c0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
169d0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
169e0 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
169f0 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
16a00 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
16a10 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c  g ways:.**.**  <
16a20 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
16a30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16a40 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
16a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16a60 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
16a70 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
16a80 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
16a90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
16aa0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
16ab0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
16ac0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
16ad0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
16ae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
16af0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f  16()</li>.**  </
16b00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
16b10 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
16b20 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
16b30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
16b40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16b50 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71  blob(),.** or sq
16b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16b70 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
16b80 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20  orce the result 
16b90 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
16ba0 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  .** format, then
16bb0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
16bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
16bd0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
16be0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a  _bytes16() to.**
16bf0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
16c00 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
16c10 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74  o not mix call t
16c20 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
16c30 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71  _text() or.** sq
16c40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
16c50 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
16c60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
16c70 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64  _bytes16().  And
16c80 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63   do not.** mix c
16c90 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
16ca0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
16cb0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
16cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16cd0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  es()..**.** The 
16ce0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
16cf0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
16d00 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
16d10 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
16d20 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
16d30 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
16d40 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
16d50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
16d60 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
16d70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
16d80 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f  alled.  The memo
16d90 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
16da0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
16db0 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72   and blobs is fr
16dc0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
16dd0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
16de0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
16df0 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
16e00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
16e10 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
16e20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
16e30 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b   etc. into .** [
16e40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
16e50 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
16e60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
16e70 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
16e80 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
16e90 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
16ea0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
16eb0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
16ec0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
16ed0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
16ee0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
16ef0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
16f00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
16f10 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
16f20 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
16f30 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
16f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
16f50 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
16f60 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
16f70 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  OMEM]..*/.const 
16f80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
16f90 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
16fa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
16fb0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
16fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
16fd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16fe0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
16ff0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
17000 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
17010 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
17020 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
17030 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
17040 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17050 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17060 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
17070 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17080 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
17090 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
170a0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
170b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
170c0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
170d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
170e0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
170f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17100 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
17110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17120 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
17130 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
17140 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
17150 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
17160 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
17170 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
17180 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
17190 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
171a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
171b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
171c0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
171d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
171e0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
171f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17200 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
17210 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
17220 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
17230 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
17240 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66  L statement]. If
17250 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
17260 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73  as.** executed s
17270 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20  uccessfully, or 
17280 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
17290 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  all, then SQLITE
172a0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
172b0 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e  .** If execution
172c0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
172d0 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
172e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
172f0 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
17300 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17310 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
17320 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
17330 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
17340 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
17350 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
17360 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
17370 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
17380 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  n of the.** [sql
17390 69 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74  ite3_stmt | virt
173a0 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49  ual machine].  I
173b0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
173c0 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a  chine has not .*
173d0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
173e0 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
173f0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
17400 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
17410 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
17420 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69  an error or an i
17430 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20  nterrupt.  (See 
17440 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
17450 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f  pt()].) .** Inco
17460 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
17470 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
17480 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
17490 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a  ns cancelled,  .
174a0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
174b0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
174c0 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b  s, and the .** [
174d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
174e0 65 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75  esult code] retu
174f0 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
17500 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a  LITE_ABORT]..*/.
17510 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
17520 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
17530 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
17540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
17550 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
17560 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
17570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17580 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
17590 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
175a0 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74  set a .** [sqlit
175b0 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c  e3_stmt | compil
175c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
175d0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63  ] object..** bac
175e0 6b 20 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61  k to it's initia
175f0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
17600 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
17610 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
17620 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
17630 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
17640 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
17650 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
17660 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
17670 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
17680 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
17690 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
176a0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
176b0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
176c0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
176d0 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ngs..*/.int sqli
176e0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
176f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
17700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17710 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
17720 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
17730 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  s.**.** The foll
17740 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
17750 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
17760 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
17770 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a  s or aggregates.
17780 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  ** or to redefin
17790 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
177a0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
177b0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
177c0 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20  egates.  The.** 
177d0 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20  difference only 
177e0 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
177f0 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
17800 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
17810 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
17820 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
17830 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
17840 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
17850 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
17860 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
17870 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
17880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
17890 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
178a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
178b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
178c0 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74  e [sqlite3 | dat
178d0 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68  abase handle] th
178e0 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20  at holds the.** 
178f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
17900 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f 20  aggregate is to 
17910 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64 65  be added or rede
17920 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67  fined. If a sing
17930 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
17940 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
17950 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
17960 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
17970 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  n SQL.** functio
17980 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
17990 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
179a0 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65  ndividually to e
179b0 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
179c0 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63  handle with whic
179d0 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75  h they will be u
179e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
179f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17a00 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
17a10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
17a20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a  to be created.**
17a30 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a   or redefined..*
17a40 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * The length of 
17a50 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
17a60 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
17a70 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
17a80 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  he .** zero-term
17a90 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
17aa0 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
17ab0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
17ac0 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
17ad0 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
17ae0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
17af0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
17b00 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
17b10 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
17b20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
17b30 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
17b40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17b50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
17b60 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
17b70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
17b80 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
17b90 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
17ba0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
17bb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
17bc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
17bd0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
17be0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
17bf0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
17c00 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
17c10 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
17c20 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
17c30 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  what .** [SQLITE
17c40 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
17c50 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
17c60 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
17c70 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
17c80 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
17c90 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
17ca0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
17cb0 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
17cc0 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
17cd0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
17ce0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
17cf0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
17d00 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
17d10 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
17d20 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
17d30 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
17d40 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
17d50 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
17d60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
17d70 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
17d80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
17d90 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
17da0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
17db0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
17dc0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
17dd0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
17de0 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
17df0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
17e00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
17e10 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
17e20 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
17e30 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
17e40 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
17e50 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
17e60 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
17e70 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
17e80 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
17e90 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
17ea0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
17eb0 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74  t care what.** t
17ec0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
17ed0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
17ee0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
17ef0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c  hould be.** [SQL
17f00 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
17f10 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
17f20 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
17f30 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
17f40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
17f50 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74  .** of the funct
17f60 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
17f70 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
17f80 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ter using.** [sq
17f90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
17fa0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
17fb0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
17fc0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
17fd0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
17fe0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
17ff0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
18000 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
18010 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
18020 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ent the SQL.** f
18030 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
18040 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
18050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
18060 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
18070 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  tation of.** the
18080 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20   xFunc callback 
18090 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
180a0 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
180b0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
180c0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
180d0 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
180e0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
180f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
18100 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
18110 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64  .** of xStep and
18120 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
18130 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
18140 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
18150 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69  delete an.** exi
18160 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
18170 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
18180 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
18190 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
181a0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  n.** callback..*
181b0 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
181c0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
181d0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
181e0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
181f0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
18200 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
18210 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
18220 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
18230 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
18240 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
18250 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74  ring perferred t
18260 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
18270 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
18280 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
18290 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
182a0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
182b0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
182c0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
182d0 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20  is used..*/.int 
182e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
182f0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
18300 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  e3 *,.  const ch
18310 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
18320 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
18330 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
18340 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28   void*,.  void (
18350 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
18360 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
18370 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
18380 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
18390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
183a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
183b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
183c0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
183d0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
183e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
183f0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
18400 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76  ite3*,.  const v
18410 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
18420 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
18430 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
18440 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20    void*,.  void 
18450 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
18460 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
18470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
18480 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
18490 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
184a0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
184b0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
184c0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
184d0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
184e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
184f0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
18500 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
18510 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
18520 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
18530 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
18540 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
18550 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
18560 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
18570 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
18580 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
18590 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
185a0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
185b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
185c0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
185d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
185e0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
185f0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
18600 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
18610 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
18620 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
18630 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
18640 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
18650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18660 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
18670 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
18680 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
18690 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
186a0 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
186b0 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
186c0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
186d0 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
186e0 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
186f0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
18700 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
18710 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
18720 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
18730 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
18740 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
18750 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
18760 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
18770 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
18780 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
18790 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
187a0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
187b0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
187c0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
187d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
187e0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
187f0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
18800 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
18810 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
18820 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
18830 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
18840 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
18850 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
18860 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
18870 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
18880 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
18890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
188a0 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
188b0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
188c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
188d0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
188e0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
188f0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
18900 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
18910 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
18920 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
18930 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
18940 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
18950 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
18960 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
18970 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
18980 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
18990 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
189a0 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
189b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
189c0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
189d0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
189e0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
189f0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
18a00 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
18a10 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
18a20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18a30 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
18a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18a50 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
18a60 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
18a70 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
18a80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
18a90 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
18aa0 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  The 4th paramete
18ab0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
18ac0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
18ad0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
18ae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
18af0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
18b00 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
18b10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
18b20 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
18b30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
18b40 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
18b50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
18b60 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
18b70 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
18b80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
18b90 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
18ba0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18bb0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
18bc0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
18bd0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  g .** [sqlite3_c
18be0 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c  olumn_blob | sql
18bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f  ite3_column_* ro
18c00 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74  utines] except t
18c10 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f  hat .** these ro
18c20 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
18c30 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  ngle [sqlite3_va
18c40 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e  lue*] pointer in
18c50 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b  stead.** of an [
18c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
18c70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
18c80 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
18c90 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
18ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
18cb0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
18cc0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36  extracts a UTF16
18cd0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
18ce0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
18cf0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
18d00 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
18d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
18d20 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
18d30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
18d40 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
18d50 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
18d60 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
18d70 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
18d80 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
18d90 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ctively..**.** T
18da0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
18db0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
18dc0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
18dd0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
18de0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
18df0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
18e00 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
18e10 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
18e20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
18e30 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
18e40 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
18e50 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
18e60 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
18e70 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
18e80 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
18e90 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
18ea0 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69  order.** words i
18eb0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 6f  f the value is o
18ec0 72 69 67 69 6e 61 6c 20 61 20 73 74 72 69 6e 67  riginal a string
18ed0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
18ee0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
18ef0 65 6e 20 69 74 20 69 73 20 64 6f 6e 65 2e 20 20  en it is done.  
18f00 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
18f10 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20  version occurs. 
18f20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   The .** [SQLITE
18f30 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
18f40 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
18f50 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
18f60 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
18f70 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
18f80 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
18f90 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
18fa0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  inter that.** is
18fb0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
18fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
18fd0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
18fe0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
18ff0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
19000 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
19010 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
19020 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
19030 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
19040 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
19050 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
19060 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
19070 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
19080 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
19090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
190a0 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  t16()].  .**.** 
190b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
190c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
190d0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
190e0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
190f0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
19100 75 70 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69  upplied the sqli
19110 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d  te3_value* param
19120 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66  eters..** Or, if
19130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
19140 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d  ue* argument com
19150 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
19160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
19170 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
19180 65 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f  e, then these ro
19190 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
191a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
191b0 20 73 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20   same thread.** 
191c0 74 68 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65  that ran [sqlite
191d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
191e0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  ]..*/.const void
191f0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
19200 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
19210 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
19220 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
19230 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19240 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19250 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
19260 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
19270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
19280 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
19290 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
192a0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
192b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
192c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
192d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
192e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
192f0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
19300 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
19310 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
19320 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
19330 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
19340 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
19350 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
19360 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
19370 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
19380 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
19390 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
193a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
193b0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
193c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
193d0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
193e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
193f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
19400 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
19410 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
19420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
19430 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
19440 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
19450 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
19460 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
19470 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
19480 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
19490 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
194a0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
194b0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
194c0 20 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72   state.  The fir
194d0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
194e0 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  tine.** is calle
194f0 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  d for a particul
19500 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20  ar aggregate, a 
19510 6e 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66  new structure of
19520 20 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20   size nBytes.** 
19530 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65  is allocated, ze
19540 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e  roed, and return
19550 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65  ed.  On subseque
19560 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68  nt calls (for th
19570 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67  e.** same aggreg
19580 61 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68  ate instance) th
19590 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
195a0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
195b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
195c0 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
195d0 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
195e0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
195f0 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
19600 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66  a..**.** The buf
19610 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73  fer allocated is
19620 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
19630 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77  ally by SQLite w
19640 68 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  han the aggregat
19650 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
19660 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
19670 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19680 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
19690 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
196a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
196b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
196c0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
196d0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
196e0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
196f0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
19700 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
19710 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
19720 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
19730 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
19740 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
19750 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
19760 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
19770 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
19780 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
19790 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
197a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
197b0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
197c0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
197d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
197e0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
197f0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
19800 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20  * The pUserData 
19810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19820 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
19830 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
19840 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
19850 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
19860 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  ] routines.** us
19870 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75  ed to register u
19880 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73  ser functions is
19890 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a   available to.**
198a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
198b0 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ion of the funct
198c0 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63  ion using this c
198d0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  all..**.** This 
198e0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
198f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
19900 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
19910 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
19920 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
19930 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
19940 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
19950 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
19960 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19970 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
19980 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
19990 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
199a0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
199b0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
199c0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
199d0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
199e0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
199f0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
19a00 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
19a10 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
19a20 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
19a30 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
19a40 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
19a50 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
19a60 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
19a70 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
19a80 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
19a90 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
19aa0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
19ab0 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
19ac0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
19ad0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
19ae0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
19af0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
19b00 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
19b10 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
19b20 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
19b30 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
19b40 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
19b50 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
19b60 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
19b70 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
19b80 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
19b90 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
19ba0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
19bb0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
19bc0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
19bd0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
19be0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
19bf0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
19c00 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
19c10 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
19c20 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
19c30 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
19c40 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
19c50 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
19c60 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
19c70 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
19c80 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
19c90 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
19ca0 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
19cb0 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
19cc0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 20   argument value 
19cd0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 53  to the current S
19ce0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  QL function.** c
19cf0 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 73 20  all, where N is 
19d00 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
19d10 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 74 61  eter. If no meta
19d20 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 73  -data has been s
19d30 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 76  et for.** that v
19d40 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e 55 4c  alue, then a NUL
19d50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
19d60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
19d70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
19d80 64 61 74 61 28 29 20 69 73 20 75 73 65 64 20 74  data() is used t
19d90 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  o associate meta
19da0 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 53 51  -data with an SQ
19db0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 72  L.** function ar
19dc0 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 69 72  gument. The thir
19dd0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
19de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
19df0 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 6f 20  meta-data.** to 
19e00 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  be associated wi
19e10 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 72 20  th the Nth user 
19e20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
19e30 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 6f 75  t value. The fou
19e40 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rth.** parameter
19e50 20 73 70 65 63 69 66 69 65 73 20 61 20 64 65 73   specifies a des
19e60 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 69 6c  tructor that wil
19e70 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 20 74  l be called on t
19e80 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 74 61  he meta-.** data
19e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 6c 65   pointer to rele
19ea0 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 20 69  ase it when it i
19eb0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
19ec0 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a 2a 2a  ired. If the .**
19ed0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 4e   destructor is N
19ee0 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 20 69  ULL, it is not i
19ef0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  nvoked..**.** In
19f00 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
19f10 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
19f20 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
19f30 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
19f40 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
19f50 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
19f60 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
19f70 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
19f80 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
19f90 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
19fa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
19fb0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
19fc0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
19fd0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
19fe0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
19ff0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1a000 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
1a010 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1a020 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1a030 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1a040 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1a050 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
1a060 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
1a070 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
1a080 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1a090 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
1a0a0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
1a0b0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
1a0c0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
1a0d0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
1a0e0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
1a0f0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
1a100 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
1a110 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
1a120 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
1a130 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1a140 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
1a150 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
1a160 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
1a170 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
1a180 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
1a190 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
1a1a0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
1a1b0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
1a1c0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
1a1d0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
1a1e0 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
1a1f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
1a200 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
1a210 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
1a220 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
1a230 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
1a240 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
1a250 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
1a260 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
1a270 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
1a280 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
1a290 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
1a2a0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
1a2b0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
1a2c0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
1a2d0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
1a2e0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
1a2f0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
1a300 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
1a310 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
1a320 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
1a330 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
1a340 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
1a350 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
1a360 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
1a370 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1a380 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
1a390 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
1a3a0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
1a3b0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
1a3c0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
1a3d0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
1a3e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1a3f0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
1a400 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
1a410 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
1a420 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
1a430 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
1a440 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
1a450 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
1a460 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
1a470 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
1a480 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
1a490 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
1a4a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1a4b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
1a4c0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
1a4d0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a  much like the .*
1a4e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1a4f0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
1a500 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66  ind_*] family of
1a510 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a   functions used.
1a520 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ** to bind value
1a530 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
1a540 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
1a550 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1a560 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  Refer to the.** 
1a570 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1a580 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
1a590 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  d_* documentatio
1a5a0 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
1a5b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1a5c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a5d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1a5e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1a5f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
1a600 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
1a610 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
1a620 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
1a630 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
1a640 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70  ption.  The.** p
1a650 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1a660 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1a670 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1a680 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
1a690 2a 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66  * is the text of
1a6a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1a6b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
1a6c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
1a6d0 69 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66  ig() cause the f
1a6e0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1a6f0 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72  tation.** to thr
1a700 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64  ow and error ind
1a710 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
1a720 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
1a730 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
1a740 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
1a750 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
1a760 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
1a770 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  om within the sa
1a780 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
1a790 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1a7a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a7b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1a7c0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2e 0a  ntext] pointer..
1a7d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1a7e0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
1a7f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
1a800 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1a810 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1a820 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a830 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
1a840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
1a850 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
1a860 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1a870 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1a880 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
1a890 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
1a8a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
1a8b0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1a8c0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1a8d0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
1a8e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
1a8f0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
1a900 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
1a910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
1a920 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
1a930 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1a940 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a950 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
1a960 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
1a970 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a980 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
1a990 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
1a9a0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
1a9b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
1a9c0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
1a9d0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
1a9e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
1a9f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1aa00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1aa10 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1aa20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1aa30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
1aa40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1aa50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1aa60 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1aa70 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1aa80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
1aa90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1aaa0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
1aab0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
1aac0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
1aad0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
1aae0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
1aaf0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1ab00 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
1ab10 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
1ab20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1ab30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1ab40 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
1ab50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1ab60 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
1ab70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1ab80 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1ab90 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
1aba0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
1abb0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
1abc0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
1abd0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
1abe0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
1abf0 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
1ac00 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  * [sqlite3*] han
1ac10 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73  dle specified as
1ac20 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1ac30 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent. .**.** The 
1ac40 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
1ac50 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1ac60 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
1ac70 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
1ac80 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
1ac90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1aca0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1acb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1acc0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
1acd0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
1ace0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1acf0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20  collation16().  
1ad00 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
1ad10 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
1ad20 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ad30 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
1ad40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
1ad50 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  ird argument mus
1ad60 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
1ad70 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
1ad80 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
1ad90 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
1ada0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
1adb0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
1adc0 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
1add0 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
1ade0 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
1adf0 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
1ae00 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
1ae10 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
1ae20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
1ae30 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
1ae40 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
1ae50 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  tively..**.** A 
1ae60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
1ae70 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
1ae80 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
1ae90 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
1aea0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  .** argument. If
1aeb0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
1aec0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
1aed0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1aee0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
1aef0 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
1af00 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
1af10 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63  it anymore). Eac
1af20 68 20 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a  h time the user.
1af30 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
1af40 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
1af50 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
1af60 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1af70 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
1af80 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1af90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
1afa0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1afb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
1afc0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1afd0 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
1afe0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1aff0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1b000 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
1b010 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72   user-supplied r
1b020 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
1b030 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
1b040 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
1b050 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20   [length, data] 
1b060 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
1b070 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
1b080 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
1b090 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1b0a0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
1b0b0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
1b0c0 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
1b0d0 69 73 74 65 72 65 64 2e 20 54 68 65 20 75 73 65  istered. The use
1b0e0 72 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  r routine should
1b0f0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
1b100 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
1b110 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
1b120 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
1b130 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
1b140 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
1b150 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
1b160 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
1b170 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
1b180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b190 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1b1a0 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
1b1b0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
1b1c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
1b1d0 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69  ** excapt that i
1b1e0 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
1b1f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
1b200 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1b210 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
1b220 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
1b230 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
1b240 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
1b250 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
1b260 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
1b270 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
1b280 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1b290 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
1b2a0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1b2b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1b2c0 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f  _v2().  Collatio
1b2d0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
1b2e0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
1b2f0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
1b300 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
1b310 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
1b320 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
1b330 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
1b340 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1b350 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
1b360 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
1b370 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
1b380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
1b390 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
1b3a0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
1b3b0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
1b3c0 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  nd.** subject to
1b3d0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1b3e0 65 20 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65  e releases.  The
1b3f0 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e   other collation
1b400 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e   creation.** fun
1b410 63 74 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c  ctions are stabl
1b420 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1b430 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1b440 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
1b450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1b460 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
1b470 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
1b480 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
1b490 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1b4a0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
1b4b0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
1b4c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b4d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
1b4e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
1b4f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
1b500 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
1b510 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
1b520 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
1b530 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1b540 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1b550 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
1b560 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
1b570 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1b580 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
1b590 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
1b5a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
1b5b0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
1b5c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
1b5d0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
1b5e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1b5f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
1b600 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
1b610 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
1b620 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
1b630 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  ks.**.** To avoi
1b640 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
1b650 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
1b660 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
1b670 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
1b680 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
1b690 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
1b6a0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
1b6b0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
1b6c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1b6d0 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
1b6e0 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
1b6f0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1b700 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1b710 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
1b720 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
1b730 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
1b740 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
1b750 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1b760 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
1b770 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
1b780 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
1b790 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
1b7a0 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
1b7b0 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
1b7c0 64 20 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73  d in UTF-8. If s
1b7d0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1b7e0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
1b7f0 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a  sed, the names.*
1b800 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  * are passed as 
1b810 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
1b820 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1b830 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65  der. A call to e
1b840 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ither.** functio
1b850 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
1b860 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
1b870 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1b880 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1b890 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
1b8a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
1b8b0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
1b8c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1b8d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
1b8e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
1b8f0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
1b900 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1b910 31 36 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64  16(). The second
1b920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1b930 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e   database.** han
1b940 64 6c 65 2e 20 54 68 65 20 74 68 69 72 64 20 61  dle. The third a
1b950 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
1b960 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
1b970 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
1b980 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ], or.** [SQLITE
1b990 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
1b9a0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
1b9b0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
1b9c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
1b9d0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
1b9e0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68  ion required. Th
1b9f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ba00 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
1ba10 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
1ba20 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
1ba30 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
1ba40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ba50 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
1ba60 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
1ba70 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
1ba80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1ba90 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
1baa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1bab0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
1bac0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
1bad0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
1bae0 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
1baf0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
1bb00 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
1bb10 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
1bb20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1bb30 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1bb40 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
1bb50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1bb60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1bb70 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
1bb80 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
1bb90 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
1bba0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
1bbb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1bbc0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
1bbd0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
1bbe0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
1bbf0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
1bc00 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
1bc10 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
1bc20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
1bc30 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
1bc40 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
1bc50 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
1bc60 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
1bc70 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
1bc80 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
1bc90 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
1bca0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1bcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1bcc0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1bcd0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1bce0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1bcf0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1bd00 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
1bd10 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
1bd20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
1bd30 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
1bd40 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
1bd50 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
1bd60 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
1bd70 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
1bd80 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
1bd90 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
1bda0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
1bdb0 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
1bdc0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
1bdd0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
1bde0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
1bdf0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
1be00 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
1be10 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
1be20 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
1be30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1be40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1be50 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
1be60 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
1be70 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
1be80 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
1be90 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
1bea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1beb0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
1bec0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
1bed0 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ime.**.** This f
1bee0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
1bef0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
1bf00 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
1bf10 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62  cution.** a numb
1bf20 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
1bf30 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
1bf40 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
1bf50 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
1bf60 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
1bf70 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
1bf80 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
1bf90 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  h .** millisecon
1bfa0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
1bfb0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
1bfc0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
1bfd0 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e   up to .** the n
1bfe0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
1bff0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
1c000 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1c010 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20  ep actually .** 
1c020 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
1c030 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1c040 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
1c050 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
1c060 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
1c070 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
1c080 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
1c090 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
1c0a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1c0b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1c0c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
1c0d0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
1c0e0 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
1c0f0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
1c100 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
1c110 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20   Files.**.** If 
1c120 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
1c130 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
1c140 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
1c150 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
1c160 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
1c170 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
1c180 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
1c190 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
1c1a0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
1c1b0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
1c1c0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
1c1d0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
1c1e0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
1c1f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
1c200 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
1c210 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
1c220 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
1c230 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
1c240 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65  tory..**.** Once
1c250 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c260 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1c270 64 2c 20 63 68 61 6e 67 69 6e 67 20 74 68 69 73  d, changing this
1c280 20 76 61 72 69 61 62 6c 65 20 77 69 6c 6c 0a 2a   variable will.*
1c290 2a 20 69 6e 76 61 6c 69 64 61 74 65 20 74 68 65  * invalidate the
1c2a0 20 63 75 72 72 65 6e 74 20 74 65 6d 70 6f 72 61   current tempora
1c2b0 72 79 20 64 61 74 61 62 61 73 65 2c 20 69 66 20  ry database, if 
1c2c0 61 6e 79 2e 20 20 47 65 6e 65 72 61 6c 6c 79 20  any.  Generally 
1c2d0 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a 20 69 74 20  speaking,.** it 
1c2e0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 69  is not safe to i
1c2f0 6e 76 6f 6b 65 20 74 68 69 73 20 72 6f 75 74 69  nvoke this routi
1c300 6e 65 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ne after [sqlite
1c310 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 0a 2a 2a  3_open()] has.**
1c320 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f   been called..*/
1c330 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
1c340 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
1c350 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
1c360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
1c370 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1c380 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20  e Databse Is In 
1c390 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
1c3a0 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73  .**.** Test to s
1c3b0 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ee whether or no
1c3c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  t the database c
1c3d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
1c3e0 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f  autocommit.** mo
1c3f0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45  de.  Return TRUE
1c400 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41   if it is and FA
1c410 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74  LSE if not.  Aut
1c420 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
1c430 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  on.** by default
1c440 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73  .  Autocommit is
1c450 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
1c460 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61  EGIN statement a
1c470 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20  nd reenabled.** 
1c480 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d  by the next COMM
1c490 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a  IT or ROLLBACK..
1c4a0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1c4b0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
1c4c0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
1c4d0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
1c4e0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
1c4f0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
1c500 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
1c510 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
1c520 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
1c530 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
1c540 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
1c550 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
1c560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c570 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61  EF:  Find The Da
1c580 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41 73  tabase Handle As
1c590 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41 20  sociated With A 
1c5a0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1c5b0 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  nt.**.** Return 
1c5c0 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
1c5d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
1c5e0 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 71  o which a.** [sq
1c5f0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
1c600 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c610 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 69   belongs..** Thi
1c620 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61  s is the same da
1c630 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68  tabase handle th
1c640 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69  at was.** the fi
1c650 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1c660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1c670 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
1c680 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68  s variants.** th
1c690 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63  at was used to c
1c6a0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
1c6b0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
1c6c0 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74   place..*/.sqlit
1c6d0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
1c6e0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
1c6f0 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  mt*);.../*.** CA
1c700 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
1c710 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
1c720 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
1c730 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ks.**.** These r
1c740 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69 73  outines.** regis
1c750 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1c760 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e 76  ctions to be inv
1c770 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
1c780 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 69  transaction.** i
1c790 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20 72  s committed or r
1c7a0 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68 65  olled back.  The
1c7b0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
1c7c0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1c7d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c7e0 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c  ack.  If the cal
1c7f0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
1c800 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
1c810 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
1c820 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63  zero, then the c
1c830 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
1c840 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
1c850 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
1c860 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
1c870 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
1c880 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
1c890 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
1c8a0 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
1c8b0 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
1c8c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ed..**.** Regist
1c8d0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
1c8e0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
1c8f0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
1c900 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
1c910 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
1c920 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
1c930 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
1c940 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  een .** rolled b
1c950 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
1c960 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
1c970 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
1c980 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
1c990 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
1c9a0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
1c9b0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
1c9c0 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a 20   occur. The .** 
1c9d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
1c9e0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
1c9f0 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
1ca00 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
1ca10 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73 65  .** back because
1ca20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ca30 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1ca40 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1ca50 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  are experimental
1ca60 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20   interfaces and 
1ca70 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
1ca80 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  hange..*/.void *
1ca90 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
1caa0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
1cab0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1cac0 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
1cad0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
1cae0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1caf0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
1cb00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cb10 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
1cb20 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
1cb30 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 65  llbacks.**.** Re
1cb40 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 63  gister a callbac
1cb50 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  k function with 
1cb60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cb70 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
1cb80 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1cb90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1cba0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1cbb0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
1cbc0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
1cbd0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
1cbe0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
1cbf0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
1cc00 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
1cc10 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  on for the same 
1cc20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1cc30 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
1cc40 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
1cc50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1cc60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1cc70 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
1cc80 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a   invoke when a .
1cc90 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
1cca0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
1ccb0 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72 73  eleted. The firs
1ccc0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1ccd0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  e callback is.**
1cce0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1ccf0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1cd00 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
1cd10 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63 6f  hook(). The seco
1cd20 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  nd callback .** 
1cd30 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
1cd40 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  of SQLITE_INSERT
1cd50 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  , SQLITE_DELETE 
1cd60 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  or SQLITE_UPDATE
1cd70 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  , depending.** o
1cd80 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
1cd90 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
1cda0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
1cdb0 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69 72  nvoked. The thir
1cdc0 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
1cdd0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
1cde0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1cdf0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
1ce00 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1ce10 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
1ce20 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
1ce30 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65 20  fected row. The 
1ce40 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
1ce50 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20  arameter is .** 
1ce60 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
1ce70 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73   row. In the cas
1ce80 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
1ce90 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
1cea0 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20  d after .** the 
1ceb0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
1cec0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
1ced0 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
1cee0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
1cef0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
1cf00 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
1cf10 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
1cf20 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
1cf30 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
1cf40 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
1cf50 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
1cf60 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1cf70 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
1cf80 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ue is returned..
1cf90 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  ** Otherwise NUL
1cfa0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
1cfb0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1cfc0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
1cfd0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
1cfe0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
1cff0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
1d000 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
1d010 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
1d020 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
1d030 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
1d040 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
1d050 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a  Pager Cache.**.*
1d060 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
1d070 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1d080 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
1d090 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1d0a0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
1d0b0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
1d0c0 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65  es between conne
1d0d0 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61  ctions to the sa
1d0e0 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20  me database..** 
1d0f0 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
1d100 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
1d110 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64  nt is true and d
1d120 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
1d130 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61  rgument.** is fa
1d140 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e  lse..**.** Begin
1d150 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20 76  ning in SQLite v
1d160 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63 61  ersion 3.5.0, ca
1d170 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
1d180 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
1d190 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e  led.** for an en
1d1a0 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20 49  tire process.  I
1d1b0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
1d1c0 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72   of SQLite, shar
1d1d0 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  ing was.** enabl
1d1e0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
1d1f0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
1d200 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
1d210 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
1d220 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
1d230 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
1d240 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
1d250 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
1d260 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1d270 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1d280 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
1d290 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1d2a0 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
1d2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d2c0 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
1d2d0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 74  e sharing mode t
1d2e0 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65 66  hat was.** in ef
1d2f0 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
1d300 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
1d310 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
1d320 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
1d330 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
1d340 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65  ared cache.  Whe
1d350 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
1d360 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
1d370 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
1d380 5f 6d 6f 64 75 6c 65 28 29 20 41 50 49 20 75 73  _module() API us
1d390 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ed to register.*
1d3a0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
1d3b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
1d3c0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
1d3d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1d3e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d3f0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
1d400 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ache was.** enab
1d410 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
1d420 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
1d430 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  n [SQLITE_ERROR 
1d440 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  | error code].**
1d450 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
1d460 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
1d470 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
1d480 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1d490 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 20 63  t for backward c
1d4a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
1d4b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
1d4c0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1d4d0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1d4e0 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
1d4f0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
1d500 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  mory.**.** Attem
1d510 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  pt to free N byt
1d520 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
1d530 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
1d540 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
1d550 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1d560 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
1d570 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
1d580 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d  ry (example: mem
1d590 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ory .** used to 
1d5a0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
1d5b0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
1d5c0 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a  performance)..**
1d5d0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1d5e0 6e 20 69 73 20 6e 6f 74 20 61 20 70 61 72 74 20  n is not a part 
1d5f0 6f 66 20 73 74 61 6e 64 61 72 64 20 62 75 69 6c  of standard buil
1d600 64 73 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 20  ds.  It is only 
1d610 63 72 65 61 74 65 64 0a 2a 2a 20 69 66 20 53 51  created.** if SQ
1d620 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1d630 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
1d640 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
1d650 41 4e 41 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e  ANAGEMENT macro.
1d660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d670 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
1d680 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1d690 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
1d6a0 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
1d6b0 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61  ze.**.** Place a
1d6c0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
1d6d0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
1d6e0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
1d6f0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
1d700 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 20  .** by SQLite.  
1d710 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
1d720 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
1d730 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20  uested .** that 
1d740 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
1d750 20 73 70 65 63 69 66 69 65 64 20 6c 69 6d 69 74   specified limit
1d760 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
1d770 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a  se_memory()] is.
1d780 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  ** invoked one o
1d790 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
1d7a0 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
1d7b0 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
1d7c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d  location.** is m
1d7d0 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  ade..**.** The l
1d7e0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
1d7f0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
1d800 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
1d810 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
1d820 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
1d830 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
1d840 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
1d850 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
1d860 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
1d870 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
1d880 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
1d890 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
1d8a0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
1d8b0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
1d8c0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
1d8d0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
1d8e0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
1d8f0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
1d900 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
1d910 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
1d920 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
1d930 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
1d940 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
1d950 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
1d960 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
1d970 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
1d980 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
1d990 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
1d9a0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
1d9b0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
1d9c0 42 75 74 20 69 66 20 69 74 0a 2a 2a 20 69 73 20  But if it.** is 
1d9d0 75 6e 61 62 6c 65 20 74 6f 20 72 65 64 75 63 65  unable to reduce
1d9e0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 62 65   memory usage be
1d9f0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 6c 69 6d  low the soft lim
1da00 69 74 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69  it, execution wi
1da10 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77  ll.** continue w
1da20 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20  ithout error or 
1da30 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54  notification.  T
1da40 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
1da50 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c  imit is .** call
1da60 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
1da70 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
1da80 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ry only..**.** T
1da90 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1daa0 69 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  it is implemente
1dab0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
1dac0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
1dad0 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  m()].** interfac
1dae0 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  e.  Only a singl
1daf0 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20 69  e memory alarm i
1db00 73 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  s available in t
1db10 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 69 6d  he default.** im
1db20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1db30 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1db40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
1db50 6e 20 61 6c 73 6f 20 75 73 65 73 20 74 68 65 0a  n also uses the.
1db60 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20  ** memory alarm 
1db70 69 6e 74 65 72 66 61 63 65 20 69 74 20 77 69 6c  interface it wil
1db80 6c 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68  l interfere with
1db90 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
1dba0 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  f the.** soft he
1dbb0 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 75 6e 64  ap limit and und
1dbc0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 20  efined behavior 
1dbd0 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20 20 0a 2a  will result.  .*
1dbe0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1dbf0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1dc00 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
1dc10 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
1dc20 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
1dc30 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
1dc40 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
1dc50 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1dc60 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
1dc70 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
1dc80 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
1dc90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1dca0 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
1dcb0 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
1dcc0 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
1dcd0 65 61 64 73 2e 20 20 54 68 65 20 76 61 6c 75 65  eads.  The value
1dce0 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
1dcf0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
1dd00 69 74 0a 2a 2a 20 69 73 20 61 6e 20 62 6f 75 6e  it.** is an boun
1dd10 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d  d on the total m
1dd20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1dd30 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73   for all threads
1dd40 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  .  In.** version
1dd50 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
1dd60 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
1dd70 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
1dd80 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
1dd90 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
1dda0 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
1ddb0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
1ddc0 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
1ddd0 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72   CAPI3REF:  Extr
1dde0 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
1ddf0 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
1de00 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69   Table.**.** Thi
1de10 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
1de20 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61  urns meta-data a
1de30 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
1de40 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
1de50 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a  ific database.**
1de60 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
1de70 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  e using the conn
1de80 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61  ection handle pa
1de90 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
1dea0 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61  t function .** a
1deb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
1dec0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
1ded0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
1dee0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
1def0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1df00 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66  rs to .** this f
1df10 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63  unction. The sec
1df20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1df30 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
1df40 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1df50 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
1df60 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61  , "temp" or an a
1df70 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1df80 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
1df90 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
1dfa0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20  ble or NULL. If 
1dfb0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
1dfc0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
1dfd0 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
1dfe0 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
1dff0 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
1e000 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61  same algorithm a
1e010 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
1e020 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a  ngine uses to .*
1e030 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
1e040 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
1e050 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
1e060 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
1e070 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1e080 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
1e090 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
1e0a0 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65   column .** name
1e0b0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
1e0c0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
1e0d0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
1e0e0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
1e0f0 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  s .** may be NUL
1e100 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e  L..**.** Meta in
1e110 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74  formation is ret
1e120 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
1e130 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
1e140 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
1e150 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e  as.** the 5th an
1e160 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
1e170 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
1e180 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66  function. Any of
1e190 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d   these .** argum
1e1a0 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ents may be NULL
1e1b0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
1e1c0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1e1d0 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
1e1e0 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  a .** informatio
1e1f0 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a  n is ommitted..*
1e200 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61  *.** <pre>.** Pa
1e210 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70  rameter     Outp
1e220 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73  ut Type      Des
1e230 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d  cription.** ----
1e240 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e250 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1e260 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20  **.**   5th     
1e270 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
1e280 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a       Data type.*
1e290 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20  *   6th         
1e2a0 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
1e2b0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Name of the def
1e2c0 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
1e2d0 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74  equence .**   7t
1e2e0 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
1e2f0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
1e300 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61  if the column ha
1e310 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
1e320 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68  straint.**   8th
1e330 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1e340 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1e350 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1e360 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
1e370 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68  ARY KEY.**   9th
1e380 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1e390 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1e3a0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1e3b0 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a  AUTOINCREMENT.**
1e3c0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a   </pre>.**.**.**
1e3d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e   The memory poin
1e3e0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
1e3f0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
1e400 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
1e410 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  e .** declaratio
1e420 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
1e430 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
1e440 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
1e450 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63  l the next .** c
1e460 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74  all to any sqlit
1e470 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
1e480 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
1e490 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
1e4a0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
1e4b0 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69   then an error i
1e4c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1e4d0 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
1e4e0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
1e4f0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
1e500 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20  _rowid_" and an 
1e510 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d  .** INTEGER PRIM
1e520 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68  ARY KEY column h
1e530 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
1e540 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
1e550 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a  n the output .**
1e560 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1e570 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
1e580 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1e590 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65  column. If there
1e5a0 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
1e5b0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50  itly declared IP
1e5c0 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  K column, then t
1e5d0 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65  he output parame
1e5e0 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
1e5f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a  .** follows:.**.
1e600 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
1e610 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
1e620 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
1e630 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
1e640 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
1e650 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
1e660 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
1e670 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
1e680 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
1e690 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
1e6a0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
1e6b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
1e6c0 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
1e6d0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
1e6e0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
1e6f0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
1e700 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
1e710 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
1e720 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
1e730 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
1e740 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f   SQLITE error co
1e750 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  de is returned a
1e760 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
1e770 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74  age.** left in t
1e780 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
1e790 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  le (to be retrie
1e7a0 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
1e7b0 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
1e7c0 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
1e7d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
1e7e0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
1e7f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
1e800 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  he.** SQLITE_ENA
1e810 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1e820 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
1e830 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
1e840 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e850 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
1e860 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
1e870 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1e880 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
1e890 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
1e8a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
1e8b0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
1e8c0 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
1e8d0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
1e8e0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
1e8f0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
1e900 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
1e910 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
1e920 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
1e930 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
1e940 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
1e950 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
1e960 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
1e970 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
1e980 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
1e990 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
1e9a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1e9b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
1e9c0 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
1e9d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
1e9e0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
1e9f0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
1ea00 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
1ea10 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
1ea20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
1ea30 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
1ea40 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
1ea50 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
1ea60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
1ea70 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
1ea80 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e  olums is auto-in
1ea90 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
1eaa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1eab0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
1eac0 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74  .**.** Attempt t
1ead0 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
1eae0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
1eaf0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
1eb00 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
1eb10 65 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f  e.  The entry po
1eb20 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a  int is zProc.  z
1eb30 50 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e  Proc may be 0 in
1eb40 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a   which case the.
1eb50 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  ** name of the e
1eb60 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
1eb70 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
1eb80 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
1eb90 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53  .**.** Return [S
1eba0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1ebb0 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
1ebc0 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
1ebd0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
1ebe0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  .**.** If an err
1ebf0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
1ec00 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
1ec10 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72   then fill *pzEr
1ec20 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72  rMsg with .** er
1ec30 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
1ec40 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  .  The calling f
1ec50 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66  unction should f
1ec60 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a  ree this memory.
1ec70 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ** by calling [s
1ec80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1ec90 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20  **.** Extension 
1eca0 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
1ecb0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1ecc0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
1ecd0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a  ad_extension()].
1ece0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
1ecf0 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20  ing this API or 
1ed00 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
1ed10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
1ed20 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
1ed30 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
1ed40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ed50 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
1ed60 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
1ed70 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
1ed80 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
1ed90 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
1eda0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
1edb0 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
1edc0 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
1edd0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
1ede0 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
1edf0 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
1ee00 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
1ee10 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
1ee20 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
1ee30 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
1ee40 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
1ee50 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
1ee60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
1ee70 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
1ee80 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
1ee90 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  g.**.** So as no
1eea0 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
1eeb0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
1eec0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
1eed0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
1eee0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
1eef0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
1ef00 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
1ef10 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
1ef20 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
1ef30 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
1ef40 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
1ef50 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
1ef60 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69  llowing.** API i
1ef70 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
1ef80 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
1ef90 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1efa0 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
1efb0 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69  nd.** off.  It i
1efc0 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
1efd0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  .  See ticket #1
1efe0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20  863..**.** Call 
1eff0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1f000 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75  h onoff==1 to tu
1f010 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  rn extension loa
1f020 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63  ding on.** and c
1f030 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
1f040 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20  f==0 to turn it 
1f050 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
1f060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1f070 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
1f080 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62  sion(sqlite3 *db
1f090 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1f0a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f0b0 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73  ake Arrangements
1f0c0 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c   To Automaticall
1f0d0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
1f0e0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ion.**.** Regist
1f0f0 65 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  er an extension 
1f100 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
1f110 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
1f120 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  y invoked.** whe
1f130 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61  never a new data
1f140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f150 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a  is opened using.
1f160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
1f170 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1f180 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
1f190 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
1f1a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
1f1b0 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
1f1c0 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
1f1d0 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
1f1e0 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
1f1f0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
1f200 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
1f210 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
1f220 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
1f230 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65  all new database
1f240 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a   connections..**
1f250 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78  .** Duplicate ex
1f260 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
1f270 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
1f280 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
1f290 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
1f2a0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
1f2b0 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
1f2c0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ess..**.** This 
1f2d0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
1f2e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1f2f0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
1f300 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73  array.** that is
1f310 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d   obtained from m
1f320 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75  alloc().  If you
1f330 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
1f340 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e  ak.** checker on
1f350 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
1f360 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
1f370 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
1f380 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68  his.** array, th
1f390 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  en invoke [sqlit
1f3a0 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74  e3_automatic_ext
1f3b0 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20  ension_reset()] 
1f3c0 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74  prior.** to shut
1f3d0 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
1f3e0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41   memory..**.** A
1f3f0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1f400 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
1f410 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a   all threads..**
1f420 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1f430 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1f440 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
1f450 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
1f460 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
1f470 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1f480 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1f490 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
1f4a0 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74  nsion(void *xEnt
1f4b0 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a  ryPoint);.../*.*
1f4c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1f4d0 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
1f4e0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
1f4f0 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20  .** Disable all 
1f500 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1f510 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20  tered automatic 
1f520 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69  extensions.  Thi
1f530 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  s.** routine und
1f540 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
1f550 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c  f all prior [sql
1f560 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65  ite3_automatic_e
1f570 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
1f580 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  alls..**.** This
1f590 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61   call disabled a
1f5a0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1f5b0 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
1f5c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
1f5d0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
1f5e0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1f5f0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1f600 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
1f610 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1f620 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
1f630 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1f640 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
1f650 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
1f660 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
1f670 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
1f680 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
1f690 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
1f6a0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
1f6b0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
1f6c0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1f6d0 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
1f6e0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
1f6f0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
1f700 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
1f710 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
1f720 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
1f730 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
1f740 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
1f750 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
1f760 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
1f770 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
1f780 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1f790 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1f7a0 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
1f7b0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
1f7c0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
1f7d0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
1f7e0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
1f7f0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
1f800 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
1f810 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
1f820 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
1f830 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
1f840 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
1f850 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f860 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
1f870 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
1f880 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
1f890 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
1f8a0 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
1f8b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f8c0 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
1f8d0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
1f8e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1f8f0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
1f900 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
1f910 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69  /*.** A module i
1f920 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72  s a class of vir
1f930 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61  tual tables.  Ea
1f940 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66  ch module is def
1f950 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e  ined.** by an in
1f960 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
1f970 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
1f980 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75  e.  This structu
1f990 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d  re consists.** m
1f9a0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
1f9b0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
1f9c0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
1f9d0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
1f9e0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
1f9f0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
1fa00 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
1fa10 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
1fa20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
1fa30 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
1fa40 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
1fa50 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
1fa60 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
1fa70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
1fa80 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
1fa90 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
1faa0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
1fab0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
1fac0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
1fad0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
1fae0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
1faf0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
1fb00 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
1fb10 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1fb20 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
1fb30 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
1fb40 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
1fb50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1fb60 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
1fb70 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
1fb80 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1fb90 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
1fba0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
1fbb0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
1fbc0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
1fbd0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
1fbe0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
1fbf0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
1fc00 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
1fc10 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
1fc20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
1fc30 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
1fc40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fc50 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
1fc60 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
1fc70 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
1fc80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1fc90 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
1fca0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
1fcb0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
1fcc0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
1fcd0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1fce0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
1fcf0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
1fd00 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
1fd10 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
1fd20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1fd30 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
1fd40 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
1fd50 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
1fd60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
1fd70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1fd80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
1fd90 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
1fda0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1fdb0 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
1fdc0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1fdd0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
1fde0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1fdf0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
1fe00 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
1fe10 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1fe20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
1fe30 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
1fe40 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
1fe50 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
1fe60 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
1fe70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
1fe80 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
1fe90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
1fea0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
1feb0 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
1fec0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
1fed0 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e   **ppArg);..  in
1fee0 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
1fef0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
1ff00 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1ff10 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ew);.};../*.** T
1ff20 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
1ff30 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
1ff40 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
1ff50 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
1ff60 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
1ff70 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
1ff80 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
1ff90 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
1ffa0 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
1ffb0 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
1ffc0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
1ffd0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
1ffe0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
1fff0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
20000 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
20010 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
20020 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
20030 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
20040 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
20050 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
20060 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
20070 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
20080 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
20090 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
200a0 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
200b0 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
200c0 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
200d0 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f  s =, <, <=, >, o
200e0 72 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69  r >=.  The parti
200f0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
20100 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
20110 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
20120 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
20130 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
20140 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
20150 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
20160 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
20170 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
20180 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
20190 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
201a0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
201b0 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
201c0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
201d0 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
201e0 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
201f0 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
20200 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
20210 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
20220 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
20230 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
20240 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
20250 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
20260 74 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45  tinos to the WHE
20270 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
20280 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
20290 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
202a0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
202b0 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
202c0 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
202d0 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
202e0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
202f0 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
20300 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
20310 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
20320 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
20330 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
20340 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
20350 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
20360 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
20370 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
20380 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
20390 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
203a0 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
203b0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
203c0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
203d0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
203e0 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
203f0 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
20400 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
20410 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
20420 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
20430 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
20440 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
20450 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
20460 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
20470 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
20480 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
20490 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
204a0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
204b0 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
204c0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
204d0 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
204e0 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
204f0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
20500 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
20510 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
20520 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
20530 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
20540 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
20550 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
20560 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
20570 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
20580 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
20590 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
205a0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
205b0 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
205c0 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
205d0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
205e0 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
205f0 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
20600 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
20610 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
20620 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
20630 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
20640 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
20650 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
20660 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
20670 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
20680 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
20690 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
206a0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
206b0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
206c0 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
206d0 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
206e0 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
206f0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
20700 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
20710 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
20720 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
20730 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
20740 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
20750 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
20760 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
20770 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
20780 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
20790 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
207a0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
207b0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
207c0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
207d0 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
207e0 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
207f0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20  straint;     /* 
20800 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
20810 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
20820 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75   */.  const stru
20830 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
20840 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
20850 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
20860 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20870 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
20880 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
20890 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
208a0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
208b0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
208c0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
208d0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
208e0 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
208f0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
20900 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
20910 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
20920 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
20930 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
20940 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
20950 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
20960 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63  ignore */.  } *c
20970 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
20980 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  ;      /* Table 
20990 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
209a0 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
209b0 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65   const int nOrde
209c0 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e  rBy;        /* N
209d0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
209e0 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
209f0 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  lause */.  const
20a00 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
20a10 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
20a20 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
20a30 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
20a40 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
20a50 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
20a60 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
20a70 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
20a80 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
20a90 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73  SC. */.  } *cons
20aa0 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t aOrderBy;     
20ab0 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
20ac0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20   BY clause */.. 
20ad0 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
20ae0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
20af0 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
20b00 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
20b10 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
20b20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
20b30 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
20b40 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
20b50 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
20b60 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
20b70 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
20b80 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
20b90 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
20ba0 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43  */.  } *const aC
20bb0 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
20bc0 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
20bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20be0 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
20bf0 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
20c00 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
20c10 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
20c20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
20c30 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
20c40 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
20c50 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
20c60 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
20c70 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
20c80 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
20c90 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
20ca0 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
20cb0 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
20cc0 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
20cd0 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
20ce0 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
20cf0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
20d00 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
20d10 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
20d20 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
20d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
20d40 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
20d50 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
20d60 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
20d70 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
20d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
20d90 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
20da0 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
20db0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
20dc0 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
20dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20de0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
20df0 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
20e00 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
20e10 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
20e20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  64../*.** This r
20e30 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
20e40 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
20e50 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74   module name wit
20e60 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63  h an SQLite.** c
20e70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75  onnection.  Modu
20e80 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
20e90 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
20ea0 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a  re creating new.
20eb0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
20ec0 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c  s on the module,
20ed0 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67   or before using
20ee0 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72   preexisting vir
20ef0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f  tual.** tables o
20f00 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  f the module..*/
20f10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
20f20 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
20f30 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20f40 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
20f50 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
20f60 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
20f70 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
20f80 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
20f90 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
20fa0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
20fb0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
20fc0 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
20fd0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
20fe0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
20ff0 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *               
21000 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
21010 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
21020 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
21030 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ./*.** This rout
21040 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ine is identical
21050 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
21060 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
21070 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a  method above,.**
21080 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
21090 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63  allows a destruc
210a0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  tor function to 
210b0 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74  be specified. It
210c0 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65   is.** even more
210d0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68   experimental th
210e0 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74  an the rest of t
210f0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
21100 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s API..*/.int sq
21110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
21120 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ule_v2(.  sqlite
21130 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
21140 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
21150 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
21160 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
21170 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
21180 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
21190 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
211a0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
211b0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
211c0 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
211d0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
211e0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  e */.  void *,  
211f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21200 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
21210 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
21220 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28  nnect */.  void(
21230 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
21240 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20  )     /* Module 
21250 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
21260 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ion */.);../*.**
21270 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
21280 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
21290 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
212a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
212b0 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
212c0 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
212d0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
212e0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
212f0 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
21300 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74  ** be taylored t
21310 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
21320 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
21330 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
21340 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70  n.   The.** purp
21350 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
21360 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
21370 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
21380 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d  ds that are comm
21390 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64  on.** to all mod
213a0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
213b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ons..**.** Virtu
213c0 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
213d0 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
213e0 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
213f0 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
21400 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
21410 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
21420 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  f() to zErrMsg. 
21430 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
21440 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
21450 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
21460 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
21470 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  y a call to sqli
21480 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72  te3_free().** pr
21490 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
214a0 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
214b0 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72   zErrMsg.  After
214c0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
214d0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
214e0 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
214f0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
21500 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
21510 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
21520 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
21530 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
21540 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
21550 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
21560 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74  d.  Note.** that
21570 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
21580 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66  () and sqlite3_f
21590 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f  ree() are used o
215a0 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  n the zErrMsg fi
215b0 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72  eld.** since vir
215c0 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20  tual tables are 
215d0 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65  commonly impleme
215e0 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65  nted in loadable
215f0 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63   extensions whic
21600 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65  h.** do not have
21610 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74   access to sqlit
21620 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73  e3MPrintf() or s
21630 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f  qlite3Free()..*/
21640 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
21650 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
21660 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
21670 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
21680 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
21690 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
216a0 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
216b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
216c0 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
216d0 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20  nally */.  char 
216e0 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20  *zErrMsg;       
216f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
21700 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d  ror message from
21710 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
21720 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  () */.  /* Virtu
21730 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
21740 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
21750 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
21760 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
21770 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f  .};../* Every mo
21780 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
21790 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
217a0 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
217b0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
217c0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
217d0 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
217e0 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
217f0 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
21800 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
21810 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
21820 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
21830 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
21840 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
21850 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
21860 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
21870 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
21880 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
21890 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
218a0 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
218b0 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
218c0 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
218d0 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
218e0 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
218f0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
21900 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
21910 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
21920 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
21930 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
21940 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
21950 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
21960 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
21970 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
21980 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
21990 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
219a0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
219b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
219c0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
219d0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
219e0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
219f0 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64   The xCreate and
21a00 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
21a10 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73  s of a module us
21a20 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
21a30 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  API.** to declar
21a40 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
21a50 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
21a60 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
21a70 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
21a80 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
21a90 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
21aa0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
21ab0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
21ac0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
21ad0 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
21ae0 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  ./*.** Virtual t
21af0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
21b00 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
21b10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
21b20 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
21b30 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
21b40 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
21b50 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
21b60 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
21b70 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
21b80 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
21b90 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
21ba0 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
21bb0 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
21bc0 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
21bd0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
21be0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
21bf0 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
21c00 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
21c10 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
21c20 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
21c30 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
21c40 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
21c50 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
21c60 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
21c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
21c80 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
21c90 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
21ca0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
21cb0 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
21cc0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
21cd0 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
21ce0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
21cf0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
21d00 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
21d10 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f  to be a place-ho
21d20 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
21d30 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
21d40 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
21d50 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
21d60 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
21d70 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
21d80 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
21d90 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
21da0 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
21db0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
21dc0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
21dd0 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
21de0 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
21df0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
21e00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
21e10 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
21e20 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
21e30 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
21e40 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
21e50 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
21e60 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
21e70 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
21e80 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
21e90 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
21ea0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
21eb0 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
21ec0 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
21ed0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
21ee0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
21ef0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
21f00 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
21f10 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
21f20 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
21f30 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
21f40 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
21f50 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
21f60 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
21f70 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
21f80 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
21f90 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
21fa0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
21fb0 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
21fc0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
21fd0 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  .**.****** EXPER
21fe0 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
21ff0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
22000 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
22010 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a  *********.*/../*
22020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20  .** CAPI3REF: A 
22030 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65  Handle To An Ope
22040 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20  n BLOB.**.** An 
22050 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
22060 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65  following opaque
22070 20 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73   structure is us
22080 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73  ed to .** repres
22090 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64  ent an blob-hand
220a0 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64  le.  A blob-hand
220b0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
220c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
220d0 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65  b_open()] and de
220e0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
220f0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
22100 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
22110 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
22120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
22130 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
22140 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
22150 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
22160 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
22170 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ections of the b
22180 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  lob..** The [sql
22190 74 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29  tie3_blob_size()
221a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
221b0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
221c0 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
221d0 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
221e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
221f0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
22200 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
22210 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
22220 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
22230 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61  I/O.**.** Open a
22240 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62   handle to the b
22250 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72  lob located in r
22260 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
22270 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61   zColumn, .** ta
22280 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
22290 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e  tabase zDb. i.e.
222a0 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74   the same blob t
222b0 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20  hat would.** be 
222c0 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
222d0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
222e0 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
222f0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
22300 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f  HERE rowid = iRo
22310 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  w;.** </pre>.**.
22320 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20  ** If the flags 
22330 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
22340 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20  -zero, the blob 
22350 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a  is opened for .*
22360 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  * read and write
22370 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69   access. If it i
22380 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62  s zero, the blob
22390 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
223a0 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a  ead .** access..
223b0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
223c0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
223d0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
223e0 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74  e new .** [sqlit
223f0 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68  e3_blob | blob h
22400 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
22410 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a  n to *ppBlob..**
22420 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
22430 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
22440 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79  rned and .** any
22450 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74   value written t
22460 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
22470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
22480 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54  the caller..** T
22490 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
224a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68  s the database-h
224b0 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65  andle error code
224c0 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
224d0 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
224e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
224f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22500 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
22510 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
22520 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
22530 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
22540 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
22550 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
22560 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
22570 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
22580 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
22590 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
225a0 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
225b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
225c0 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
225d0 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  ndle.**.** Close
225e0 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
225f0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
22600 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndle]..*/.int sq
22610 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
22620 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
22630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22640 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53  F:  Return The S
22650 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
22660 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  LOB.**.** Return
22670 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
22680 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61  es of the blob a
22690 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
226a0 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  e open .** [sqli
226b0 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
226c0 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
226d0 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  s an argument..*
226e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
226f0 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
22700 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
22710 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
22720 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
22730 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
22740 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
22750 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
22760 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
22770 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
22780 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
22790 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61  andle] into a ca
227a0 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  ller supplied bu
227b0 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
227c0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
227d0 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a  ied into buffer.
227e0 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70  ** z from the op
227f0 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
22800 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
22810 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  set..**.** On su
22820 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
22830 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
22840 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
22850 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
22860 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
22870 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
22880 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
22890 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
228a0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
228b0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
228c0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
228d0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
228e0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
228f0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
22900 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74   CAPI3REF:  Writ
22910 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
22920 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
22930 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
22940 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
22950 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20  write data into 
22960 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  an open .** [sql
22970 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
22980 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20  -handle] from a 
22990 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  user supplied bu
229a0 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
229b0 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
229c0 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66  ied from the buf
229d0 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  fer.** pointed t
229e0 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20  o by z into the 
229f0 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74  open blob, start
22a00 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
22a10 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ffset..**.** If 
22a20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
22a30 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
22a40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
22a50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
22a60 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
22a70 66 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65  for writing (the
22a80 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22a90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
22aa0 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61  b_open()].*** wa
22ab0 73 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75  s zero), this fu
22ac0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
22ad0 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
22ae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
22af0 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
22b00 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
22b10 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  ts of the blob, 
22b20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
22b30 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
22b40 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
22b50 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
22b60 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65  API. If.** offse
22b70 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
22b80 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66  s than n bytes f
22b90 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
22ba0 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51  he blob, .** [SQ
22bb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
22bc0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
22bd0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
22be0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
22bf0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
22c00 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
22c10 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
22c20 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
22c30 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
22c40 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
22c50 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
22c60 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
22c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
22c90 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
22ca0 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
22cb0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
22cc0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
22cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69  ** CAPI3REF:  Vi
22ce0 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
22cf0 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
22d00 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
22d10 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
22d20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22d30 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
22d40 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
22d50 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
22d60 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
22d70 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
22d80 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65  Most builds come
22d90 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
22da0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
22db0 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
22dc0 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
22dd0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
22de0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
22df0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
22e00 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
22e10 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
22e20 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
22e30 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
22e40 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
22e50 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
22e60 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
22e70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22e80 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
22e90 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20  n its.** name.  
22ea0 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
22eb0 65 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68  ensitive.  If th
22ec0 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
22ed0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
22ee0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
22ef0 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20   If zVfsName is 
22f00 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
22f10 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73  fault .** VFS is
22f20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
22f30 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
22f40 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
22f50 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
22f60 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20  ter().  Each.** 
22f70 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
22f80 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
22f90 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
22fa0 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
22fb0 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
22fc0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
22fd0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
22fe0 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
22ff0 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73   To make an exis
23000 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
23010 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
23020 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
23030 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
23040 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
23050 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
23060 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
23070 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
23080 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
23090 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
230a0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
230b0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
230c0 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
230d0 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
230e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
230f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
23100 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
23110 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67  ed..** .** Unreg
23120 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
23130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
23140 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
23150 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74  terface..** If t
23160 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
23170 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20  s unregistered, 
23180 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63  another VFS is c
23190 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20  hosen as.** the 
231a0 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68  default.  The ch
231b0 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77  oice for the new
231c0 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72   VFS is arbitrar
231d0 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66  y..*/.sqlite3_vf
231e0 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  s *sqlite3_vfs_f
231f0 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ind(const char *
23200 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73  zVfsName);.int s
23210 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
23220 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
23230 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b  , int makeDflt);
23240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
23250 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69  _unregister(sqli
23260 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a  te3_vfs*);../*.*
23270 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
23280 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  xes.**.** The SQ
23290 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
232a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
232b0 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63  r thread.** sync
232c0 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68  hronization.  Th
232d0 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
232e0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
232f0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
23300 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
23310 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
23320 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
23330 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
23340 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
23350 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
23360 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
23370 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
23380 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23390 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d  s .** of these m
233a0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20  utex routines.  
233b0 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69  An appropriate i
233c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
233d0 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74   is selected aut
233e0 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f  omatically at co
233f0 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65  mpile-time.  The
23400 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d   following.** im
23410 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72  plementations ar
23420 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
23430 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a  he SQLite core:.
23440 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
23450 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
23460 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_OS2.** <li>   
23470 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
23480 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
23490 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a  QLITE_MUTEX_W32.
234a0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
234b0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
234c0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
234d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
234e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
234f0 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74  is a set of rout
23500 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f  ines .** that do
23510 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
23520 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
23530 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
23540 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68   .** a single-th
23550 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
23560 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  on.  The SQLITE_
23570 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
23580 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
23590 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
235a0 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
235b0 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
235c0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
235d0 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69  use on os/2, uni
235e0 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a  x, and windows..
235f0 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  ** .** If SQLite
23600 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
23610 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  h the SQLITE_MUT
23620 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f  EX_APPDEF prepro
23630 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20  cessor.** macro 
23640 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d  defined (with "-
23650 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
23660 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e  PDEF=1"), then n
23670 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  o mutex.** imple
23680 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63  mentation is inc
23690 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c  luded with the l
236a0 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20  ibrary.  The.** 
236b0 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63 65 20  mutex interface 
236c0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
236d0 20 68 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74   here become ext
236e0 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e  ernal.** referen
236f0 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ces in the SQLit
23700 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68  e library for wh
23710 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ich implementati
23720 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70  ons.** must be p
23730 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61  rovided by the a
23740 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  pplication.  Thi
23750 73 20 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77  s facility allow
23760 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  s an.** applicat
23770 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ion that links a
23780 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f  gainst SQLite to
23790 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e   provide its own
237a0 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
237b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74  entation without
237c0 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66   having to modif
237d0 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
237e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
237f0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
23800 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
23810 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
23820 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
23830 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
23840 20 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20    If it returns 
23850 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
23860 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
23870 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
23880 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 0a  ocated.  SQLite.
23890 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
238a0 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
238b0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 54  urn an error.  T
238c0 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
238d0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
238e0 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f  alloc() is one o
238f0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
23900 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a  constants:.**.**
23910 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
23920 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
23930 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
23940 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
23950 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
23960 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
23970 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  STER.** <li>  SQ
23980 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
23990 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_MEM.** <li>  S
239a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
239b0 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20  IC_MEM2.** <li> 
239c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
239d0 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69  ATIC_PRNG.** <li
239e0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
239f0 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f  STATIC_LRU.** </
23a00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
23a10 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
23a20 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  s cause sqlite3_
23a30 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
23a40 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
23a50 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77   mutex.  The new
23a60 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
23a70 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
23a80 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
23a90 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
23aa0 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
23ab0 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
23ac0 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
23ad0 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
23ae0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
23af0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
23b00 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
23b10 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
23b20 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
23b30 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
23b40 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
23b50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
23b60 20 74 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65   to.  But SQLite
23b70 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
23b80 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
23b90 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
23ba0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
23bb0 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20   needs one.  If 
23bc0 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
23bd0 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
23be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
23bf0 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
23c00 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
23c10 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
23c20 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
23c30 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
23c40 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
23c50 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
23c60 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  AST..**.** The o
23c70 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
23c80 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
23c90 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
23ca0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
23cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
23cc0 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
23cd0 67 20 6d 75 74 65 78 2e 20 20 46 6f 75 72 20 73  g mutex.  Four s
23ce0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
23cf0 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
23d00 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
23d10 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
23d20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23d30 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
23d40 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
23d50 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
23d60 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
23d70 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
23d80 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
23d90 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
23da0 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
23db0 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
23dc0 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
23dd0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
23de0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
23df0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
23e00 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
23e10 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
23e20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 69 66  .** Note that if
23e30 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
23e40 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
23e50 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
23e60 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
23e70 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
23e80 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
23e90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
23ea0 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
23eb0 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
23ec0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
23ed0 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72 20 74 68  all.  But for th
23ee0 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74  e static .** mut
23ef0 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
23f00 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
23f10 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
23f20 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
23f30 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
23f40 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
23f50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
23f60 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 6c  e() routine deal
23f70 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 6f  locates a previo
23f80 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  usly.** allocate
23f90 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e  d dynamic mutex.
23fa0 20 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65    SQLite is care
23fb0 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ful to deallocat
23fc0 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d  e every.** dynam
23fd0 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74  ic mutex that it
23fe0 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65   allocates.  The
23ff0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
24000 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 20   must not be in 
24010 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65  .** use when the
24020 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65  y are deallocate
24030 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 74  d.  Attempting t
24040 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73  o deallocate a s
24050 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72  tatic.** mutex r
24060 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
24070 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 53  ned behavior.  S
24080 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c  QLite never deal
24090 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61  locates.** a sta
240a0 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a  tic mutex..**.**
240b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
240c0 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73  ex_enter() and s
240d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
240e0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  () routines atte
240f0 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20  mpt.** to enter 
24100 61 20 6d 75 74 65 78 2e 20 20 49 66 20 61 6e 6f  a mutex.  If ano
24110 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
24120 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
24130 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
24140 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
24150 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
24160 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
24170 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
24180 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
24190 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
241a0 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
241b0 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ace returns SQLI
241c0 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75  TE_OK.** upon su
241d0 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
241e0 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64   Mutexes created
241f0 20 75 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d 55   using SQLITE_MU
24200 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
24210 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72 65 64 20  n.** be entered 
24220 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62  multiple times b
24230 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
24240 64 2e 20 20 49 6e 20 73 75 63 68 20 63 61 73 65  d.  In such case
24250 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
24260 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
24270 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
24280 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
24290 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
242a0 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 49 66 20   can enter.  If 
242b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
242c0 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
242d0 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f 66  ny other kind of
242e0 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 74   mutex.** more t
242f0 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
24300 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24310 6e 65 64 2e 20 20 20 53 51 4c 69 74 65 20 77 69  ned.   SQLite wi
24320 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
24330 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
24340 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
24350 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a   of mutexes..**.
24360 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
24370 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
24380 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
24390 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
243a0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
243b0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
243c0 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61 76  read.  The behav
243d0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
243e0 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
243f0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24400 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
24410 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
24420 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
24430 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
24440 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
24450 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
24460 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
24470 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
24480 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
24490 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
244a0 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
244b0 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
244c0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
244d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
244e0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
244f0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
24500 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
24510 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
24520 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
24530 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
24540 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
24550 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
24560 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
24570 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
24580 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
24590 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f 75 74  Verifcation Rout
245a0 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ines.**.** The s
245b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
245c0 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
245d0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
245e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
245f0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
24600 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
24610 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
24620 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a  e SQLite core.**
24630 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73   never uses thes
24640 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70  e routines excep
24650 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65  t inside an asse
24660 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61  rt() and applica
24670 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76  tions.** are adv
24680 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74  ised to follow t
24690 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63  he lead of the c
246a0 6f 72 65 2e 20 20 54 68 65 20 63 6f 72 65 20 6f  ore.  The core o
246b0 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  nly.** provides 
246c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
246d0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
246e0 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  es when it is co
246f0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74  mpiled.** with t
24700 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he SQLITE_DEBUG 
24710 66 6c 61 67 2e 20 20 45 78 74 65 72 6e 61 6c 20  flag.  External 
24720 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
24730 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
24740 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
24750 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
24760 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
24770 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
24780 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
24790 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
247a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
247b0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
247c0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
247d0 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
247e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
247f0 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
24800 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
24810 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
24820 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ead..**.** The i
24830 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
24840 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
24850 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
24860 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
24870 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
24880 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49  ually work..** I
24890 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
248a0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
248b0 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
248c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
248d0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
248e0 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20  should at least 
248f0 70 72 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a  provide stubs.**
24900 20 74 68 61 74 20 61 6c 77 61 79 73 20 72 65 74   that always ret
24910 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74  urn true so that
24920 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65   one does not ge
24930 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73  t spurious.** as
24940 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
24950 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61  ..**.** If the a
24960 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
24970 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
24980 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24990 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f  r then.** the ro
249a0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
249b0 75 72 6e 20 31 2e 20 20 54 68 69 73 20 73 65 65  urn 1.  This see
249c0 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
249d0 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
249e0 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
249f0 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
24a00 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
24a10 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
24a20 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
24a30 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
24a40 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
24a50 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
24a60 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
24a70 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
24a80 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
24a90 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
24aa0 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
24ab0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
24ac0 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
24ad0 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
24ae0 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
24af0 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
24b00 64 6f 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  do.  The sqlite3
24b10 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
24b20 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73   .** interface s
24b30 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
24b40 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
24b50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
24b60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  /.int sqlite3_mu
24b70 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
24b80 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
24b90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
24ba0 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
24bb0 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
24bc0 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65  3REF: Mutex Type
24bd0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
24be0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
24bf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61  ()] interface ta
24c00 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
24c10 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69  ument.** which i
24c20 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
24c30 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
24c40 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
24c50 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20  ITE_MUTEX_FAST  
24c60 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
24c70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
24c80 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  X_RECURSIVE     
24c90 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
24ca0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
24cb0 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65  _MASTER    2.#de
24cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
24cd0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20  X_STATIC_MEM    
24ce0 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33     3  /* sqlite3
24cf0 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65  _malloc() */.#de
24d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
24d10 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20  X_STATIC_MEM2   
24d20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
24d30 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
24d40 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
24d50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
24d60 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
24d70 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
24d80 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
24d90 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
24da0 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
24db0 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
24dc0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74  /.../*.** Undo t
24dd0 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e  he hack that con
24de0 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70  verts floating p
24df0 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e  oint types to in
24e00 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69  teger for.** bui
24e10 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72  lds on processor
24e20 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69  s without floati
24e30 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
24e40 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
24e50 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
24e60 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64  _POINT.# undef d
24e70 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69  ouble.#endif..#i
24e80 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
24e90 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68  .}  /* End of th
24ea0 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62  e 'extern "C"' b
24eb0 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23  lock */.#endif.#
24ec0 65 6e 64 69 66 0a                                endif.