/ Hex Artifact Content
Login

Artifact 0b8875192b9cea40cf4a5d1dfda2d0172a0bd4c4:


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 36 36 20 32 30 30 37 2f  in,v 1.266 2007/
05f0: 31 30 2f 30 33 20 32 30 3a 31 35 3a 32 38 20 64  10/03 20:15:28 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 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
2180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  .**.** The 4th p
2190: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73  arameter to this
21a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 6e   interface is an
21b0: 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
21c0: 65 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 61  er that is.** pa
21d0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
21e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
21f0: 63 74 69 6f 6e 20 61 73 20 69 74 73 20 66 69 72  ction as its fir
2200: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
2210: 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 61 72 61  .** The 2nd para
2220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2230: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
2240: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2250: 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  ** columns in th
2260: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e 20  e query result. 
2270: 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
2280: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
2290: 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 72 72 61  ck.** is an arra
22a0: 79 20 6f 66 20 73 74 72 69 6e 67 73 20 68 6f 6c  y of strings hol
22b0: 64 69 6e 67 20 74 68 65 20 76 61 6c 75 65 73 20  ding the values 
22c0: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 0a  for each column.
22d0: 2a 2a 20 61 73 20 65 78 74 72 61 63 74 65 64 20  ** as extracted 
22e0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
22f0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
2300: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2310: 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2320: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
2330: 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 62  of strings.** ob
2340: 74 61 69 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  tained using [sq
2350: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2360: 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 69 6e 67  e()] and holding
2370: 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  .** the names of
2380: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   each column..**
2390: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
23a0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
23b0: 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 6f 72 20   NULL, even for 
23c0: 71 75 65 72 69 65 73 2e 20 20 41 20 4e 55 4c 4c  queries.  A NULL
23d0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
23e0: 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  not an error.  I
23f0: 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 74 68 61  t just means tha
2400: 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  t no callback.**
2410: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
2420: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72  ..**.** If an er
2430: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
2440: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
2450: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 28  uating the SQL (
2460: 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 69 6c 65  but.** not while
2470: 20 65 78 65 63 75 74 69 6e 67 20 74 68 65 20 63   executing the c
2480: 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e 20 61 6e  allback) then an
2490: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
24a0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
24b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
24c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
24d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
24e0: 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72  oc()] and.** *er
24f0: 72 6d 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20  rmsg is made to 
2500: 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65  point to that me
2510: 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c 6c  ssage.  The call
2520: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
2530: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2540: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
2550: 65 6d 6f 72 79 20 75 73 69 6e 67 20 5b 73 71 6c  emory using [sql
2560: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2570: 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c   If errmsg==NULL
2580: 2c 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20  , then no error 
2590: 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72 20  message is ever 
25a0: 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  written..**.** T
25b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25c0: 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20  is is SQLITE_OK 
25d0: 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
25e0: 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f  errors and.** so
25f0: 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  me other [SQLITE
2600: 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  _OK | return cod
2610: 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20 61  e] if there is a
2620: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68  n error.  .** Th
2630: 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 74  e particular ret
2640: 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64  urn value depend
2650: 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66  s on the type of
2660: 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69   error. .**.*/.i
2670: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
2680: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26b0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
26c0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26d0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2700: 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74  valuted */.  int
2710: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2720: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
2730: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
2740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
2750: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2770: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2780: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
2790: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
27a0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
27d0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
27e0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
27f0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2800: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
2810: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  DS: SQLITE_OK.**
2820: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
2830: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2840: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
2850: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
2860: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62   set shown.** ab
2870: 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ove in order to 
2880: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
2890: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
28a0: 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63  .** The result c
28b0: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
28c0: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
28d0: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
28e0: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
28f0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2900: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b    However, the [
2910: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2920: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2930: 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75  .** API can be u
2940: 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61 74  sed to set a dat
2950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e  abase connectoin
2960: 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20   to return more 
2970: 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75  detailed.** resu
2980: 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  lt codes..**.** 
2990: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
29a0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
29b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29c0: 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  odes].**.*/.#def
29d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
29e0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
29f0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
2a00: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
2a10: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2a20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2a30: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
2a40: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
2a50: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
2a60: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
2a70: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
2a80: 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53     2   /* NOT US
2a90: 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67  ED. Internal log
2aa0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
2ab0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
2ac0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
2ad0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
2ae0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
2af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2b00: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
2b10: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
2b20: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
2b30: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
2b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
2b50: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
2b60: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
2b70: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
2b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b90: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
2ba0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
2bb0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
2bc0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2bd0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
2be0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
2bf0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
2c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c10: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
2c20: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
2c30: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
2c40: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
2c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
2c60: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
2c70: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
2c80: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
2c90: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
2ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
2cb0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
2cc0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
2cd0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
2ce0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
2cf0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
2d00: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
2d10: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
2d20: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
2d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d40: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
2d50: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
2d60: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
2d70: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
2d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
2d90: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
2da0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
2db0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
2dc0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
2dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
2de0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
2df0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
2e00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2e10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2e20: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
2e30: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
2e40: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
2e50: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
2e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e70: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
2e80: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
2e90: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
2ea0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
2eb0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
2ec0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2ed0: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
2ee0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
2ef0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
2f00: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
2f10: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
2f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2f30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
2f40: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
2f50: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
2f60: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
2f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
2f80: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
2f90: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
2fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2fb0: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
2fc0: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
2fd0: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
2fe0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ff0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
3000: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
3010: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
3020: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
3030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3040: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
3050: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
3060: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3070: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
3080: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
3090: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
30a0: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
30b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30c0: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
30d0: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
30e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
30f0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
3100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3110: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
3120: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
3130: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
3140: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3160: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
3170: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
3180: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
3190: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
31a0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
31b0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
31c0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
31d0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
31e0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
31f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3200: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3210: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
3220: 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20   Codes.**.** In 
3230: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
3240: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
3250: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
3260: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
3270: 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c  integer.** resul
3280: 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65  t codes describe
3290: 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65  d at result-code
32a0: 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  s.  However, exp
32b0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
32c0: 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f  n that.** many o
32d0: 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  f these result c
32e0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75  odes are too cou
32f0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
3300: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
3310: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
3320: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
3330: 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73  roblems as users
3340: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
3350: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
3360: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
3370: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
3380: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
3390: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
33a0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
33b0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
33c0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
33d0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
33e0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
33f0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
3400: 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78   errors.  The ex
3410: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3420: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
3430: 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f  (or disabled) fo
3440: 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  r .** each datab
3450: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
3460: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
3470: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
3480: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
3490: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
34a0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
34b0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
34c0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
34d0: 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78   above..** We ex
34e0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
34f0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3500: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3510: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3520: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3530: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3550: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3560: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3570: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3580: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3590: 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  QLite..** .** Th
35a0: 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
35b0: 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20  for an extended 
35c0: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61  result code alwa
35d0: 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65  ys contains a re
35e0: 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79  lated.** primary
35f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20   result code as 
3600: 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61  a prefix.  Prima
3610: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ry result codes 
3620: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
3630: 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65  .** "_" characte
3640: 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73  r.  Extended res
3650: 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69  ult codes contai
3660: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
3670: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
3680: 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c   The numeric val
3690: 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65  ue of an extende
36a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61  d result code ca
36b0: 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  n be converted t
36c0: 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70  o its.** corresp
36d0: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
36e0: 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61  esult code by ma
36f0: 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f  sking off the lo
3700: 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a  wer 8 bytes..**.
3710: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
3720: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
3730: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
3740: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
3750: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
3760: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
3770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3780: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28  _READ          (
3790: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
37a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
37b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
37c0: 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54  T_READ    (SQLIT
37d0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
37e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
37f0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
3800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3810: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
3820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3830: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
3840: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3850: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
3860: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
3870: 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49  _FSYNC     (SQLI
3880: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
3890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
38a0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
38b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
38c0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
38d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
38e0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
38f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3900: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
3910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
3920: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3930: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
3940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3950: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
3960: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
3970: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
3980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3990: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
39a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
39b0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
39c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
39d0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53  BLOCKED       (S
39e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
39f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
3a00: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
3a10: 4d 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  M         (SQLIT
3a20: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
3a30: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
3a40: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
3a50: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
3a60: 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62 69 6e 61  ns.**.** Combina
3a70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c  tion of the foll
3a80: 6f 77 69 6e 67 20 62 69 74 20 76 61 6c 75 65 73  owing bit values
3a90: 20 61 72 65 20 75 73 65 64 20 61 73 20 74 68 65   are used as the
3aa0: 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65  .** third argume
3ab0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
3ac0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
3ad0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 61  terface and.** a
3ae0: 73 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  s fourth argumen
3af0: 74 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  t to the xOpen m
3b00: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
3b10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
3b20: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  ject..**.*/.#def
3b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
3b50: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
3b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3b70: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
3b80: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
3b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3ba0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
3bb0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
3bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3bd0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
3be0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
3bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c00: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
3c10: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
3c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c30: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
3c40: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
3c50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c60: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
3c70: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
3c80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3c90: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
3ca0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
3cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3cc0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
3cd0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
3ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3cf0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
3d00: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
3d10: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3d20: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
3d30: 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66   0x00002000.#def
3d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
3d50: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
3d60: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
3d70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
3d80: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
3d90: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
3da0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
3db0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
3dc0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3dd0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
3de0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
3df0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
3e00: 74 6f 72 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  tor of the follo
3e10: 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76 61 6c 75  wing.** bit valu
3e20: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
3e30: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
3e40: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
3e50: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
3e60: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
3e70: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
3e80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
3e90: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
3ea0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
3eb0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
3ec0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
3ed0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
3ee0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
3ef0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
3f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3f10: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
3f20: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
3f30: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
3f40: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
3f50: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
3f60: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
3f70: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
3f80: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
3f90: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
3fa0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
3fb0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
3fc0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
3fd0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
3fe0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
3ff0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
4000: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
4010: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
4020: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
4030: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
4040: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
4050: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
4060: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4070: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
4080: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
4090: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
40a0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
40b0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
40c0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
40d0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
40e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
40f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
4100: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4120: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
4130: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4150: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
4160: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4180: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
4190: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
41a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
41b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
41c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
41d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
41e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
41f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
4200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4210: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
4220: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
4230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4240: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
4250: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
4260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4270: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
4280: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
42a0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
42b0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
42d0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
42e0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
42f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4300: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
4310: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
4320: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
4330: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
4340: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
4350: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
4360: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
4370: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
4380: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
4390: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
43a0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
43b0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
43c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43d0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
43e0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
43f0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
4400: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
4450: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
4460: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
4470: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
4480: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
4490: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
44a0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
44b0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
44c0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
44d0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
44e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
44f0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
4500: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
4510: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
4520: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 0a  teger values as.
4530: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
4540: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
4550: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
4560: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
4570: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
4580: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
4590: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
45a0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
45b0: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
45c0: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
45d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
45e0: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
45f0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53  d.  The SQLITE_S
4600: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73  YNC_NORMAL means
4610: 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d   .** to use norm
4620: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
4630: 74 69 63 73 2e 20 20 54 68 65 20 53 51 4c 49 54  tics.  The SQLIT
4640: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
4650: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
4660: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
4670: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
4680: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
4690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46a0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
46b0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
46d0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
46e0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
46f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
4700: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
4710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4720: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
4730: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
4740: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
4750: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
4760: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
4770: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a   file in the OS.
4780: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  ** interface lay
4790: 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  er.  Individual 
47a0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70  OS interface imp
47b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
47c0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
47d0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
47e0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
47f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
4800: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
4810: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
4820: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
4830: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
4840: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
4850: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
4860: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
4870: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
4880: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
4890: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
48a0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
48b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
48c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
48d0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
48e0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
48f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
4900: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
4910: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
4920: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
4930: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
4940: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
4950: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
4960: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
4970: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
4980: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
4990: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
49a0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
49b0: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
49c0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
49d0: 20 6f 66 20 74 68 65 20 74 68 69 73 20 6f 62 6a   of the this obj
49e0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
49f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a  t defines the.**
4a00: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
4a10: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
4a20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69   operations agai
4a30: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
4a40: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  e..**.** The fla
4a50: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
4a60: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
4a70: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
4a80: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
4a90: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
4aa0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
4ab0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
4ac0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20 54 68  l fsync()..*  Th
4ad0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
4ae0: 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74  is an.** OS-X st
4af0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
4b00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
4b10: 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20  ATA flag may be 
4b20: 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e  ORed in to.** in
4b30: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
4b40: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
4b50: 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74   file and not it
4b60: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
4b70: 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a   be.** synced..*
4b80: 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  * .** The intege
4b90: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
4ba0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
4bb0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
4bc0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
4bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
4be0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
4bf0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
4c00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
4c10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
4c20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
4c30: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
4c40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
4c50: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
4c60: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
4c70: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
4c80: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
4c90: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
4ca0: 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65  e lock.  .** The
4cb0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
4cc0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f  ock() method loo
4cd0: 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ks.** to see if 
4ce0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
4cf0: 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 20  nection, either 
4d00: 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65  in this.** proce
4d10: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
4d20: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
4d30: 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53 45 52  holding an RESER
4d40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
4d50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
4d60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
4d70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
4d80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
4d90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
4da0: 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a  lse if not..** .
4db0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
4dc0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
4dd0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
4de0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
4df0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
4e00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
4e10: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
4e20: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
4e30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4e40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
4e50: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
4e60: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
4e70: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
4e80: 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  an integer opcod
4e90: 65 2e 20 20 20 54 68 65 20 74 68 69 72 64 0a 2a  e.   The third.*
4ea0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  * argument is a 
4eb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
4ec0: 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e 64 65  which is intende
4ed0: 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e 74 65  d to be a pointe
4ee0: 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75 63 74  r.** to a struct
4ef0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
4f00: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
4f10: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
4f20: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
4f30: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
4f40: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
4f50: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
4f60: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
4f70: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
4f80: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
4f90: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
4fa0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
4fb0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
4fc0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
4fd0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
4fe0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
4ff0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
5000: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
5010: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
5020: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
5030: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
5040: 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  ves opcodes less
5050: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
5060: 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41  s own use. .** A
5070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
5080: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
5090: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
50a0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
50b0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
50c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
50d0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
50e0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
50f0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
5100: 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65 72 20  des .** greater 
5110: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
5120: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a  d conflicts..**.
5130: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
5140: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
5150: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
5160: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
5170: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
5180: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
5190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
51a0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
51b0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
51c0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
51d0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
51e0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
51f0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
5200: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
5210: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
5220: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
5230: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
5240: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
5250: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
5260: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
5270: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
5280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5290: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
52a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
52b0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
52c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
52d0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
52e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
52f0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
5300: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5310: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
5320: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5330: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
5340: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5350: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
5360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5370: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
5380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5390: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
53a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
53b0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
53c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
53d0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
53e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
53f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5400: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5410: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5420: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5430: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5450: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5460: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5470: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5480: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5490: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
54a0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
54b0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
54c0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
54d0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
54e0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
54f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5500: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
5510: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
5520: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
5530: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
5540: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5550: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5560: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5570: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5580: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5590: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
55a0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
55b0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
55c0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
55d0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
55e0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
55f0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5600: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5610: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5620: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
5630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
5640: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
5650: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
5660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5670: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
5680: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
5690: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
56a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
56b0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
56c0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
56d0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
56e0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
56f0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
5700: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
5710: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
5720: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
5730: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
5740: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
5750: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
5760: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
5770: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
5780: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
5790: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
57a0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
57b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
57c0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
57d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
57e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
57f0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
5800: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
5810: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
5820: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
5830: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
5840: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5850: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
5860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
5870: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
5880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
5890: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
58a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
58b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
58c0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
58d0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
58e0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
58f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
5900: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
5910: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
5920: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
5930: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
5940: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
5950: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
5960: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
5970: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
5980: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
5990: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
59a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
59b0: 20 61 6e 64 20 74 6f 20 74 68 65 20 5b 73 71 6c   and to the [sql
59c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
59d0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
59e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
59f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
5a00: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
5a10: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
5a20: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
5a30: 6f 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46  ode cases the xF
5a40: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
5a50: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
5a60: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
5a70: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
5a80: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
5a90: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
5aa0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
5ab0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5ac0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
5ad0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5ae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
5af0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
5b00: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
5b10: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
5b20: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
5b30: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
5b40: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
5b50: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
5b60: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
5b70: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
5b80: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
5b90: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64  s defined..*/.#d
5ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
5bb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
5bc0: 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      1../*.** CAP
5bd0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
5be0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
5bf0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
5c00: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
5c10: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
5c20: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
5c30: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
5c40: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
5c50: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
5c60: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
5c70: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
5c80: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
5c90: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
5ca0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
5cb0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
5cc0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
5cd0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
5ce0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
5cf0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
5d00: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
5d10: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
5d20: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5d30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
5d40: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
5d50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5d60: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
5d70: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
5d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
5d90: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
5da0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
5db0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  the.** SQLite co
5dc0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
5dd0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
5de0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
5df0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
5e00: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
5e10: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
5e20: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
5e30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72  ..**.** The iVer
5e40: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
5e50: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
5e60: 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f 72 20  y be larger for 
5e70: 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  future.** versio
5e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
5e90: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
5ea0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
5eb0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
5ec0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
5ed0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
5ee0: 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  creased..**.** T
5ef0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
5f00: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
5f10: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
5f20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
5f30: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
5f40: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
5f50: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
5f60: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
5f70: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
5f80: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
5f90: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 76  .** Registered v
5fa0: 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b  fs modules are k
5fb0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
5fc0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
5fd0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
5fe0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
5ff0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
6000: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
6010: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
6020: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
6030: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
6040: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
6050: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
6060: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
6070: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
6080: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
6090: 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  st..**.** The pN
60a0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
60b0: 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20   only fields in 
60c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
60d0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
60e0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
60f0: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
6100: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
6110: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
6120: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
6130: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
6140: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
6150: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
6160: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
6170: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
6180: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
6190: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
61a0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
61b0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
61c0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
61d0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
61e0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
61f0: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
6200: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
6210: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
6220: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
6230: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51  odules..**.** SQ
6240: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
6250: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
6260: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
6270: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
6280: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
6290: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
62a0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
62b0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
62c0: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
62d0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
62e0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
62f0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
6300: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 5b 73  lled.  So the [s
6310: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
6320: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
6330: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
6340: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
6350: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
6360: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
6370: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e reason..**.** 
6380: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
6390: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73  nt to xOpen() is
63a0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
63b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  lags argument.**
63c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
63d0: 6e 5f 76 32 28 29 5d 2e 20 20 49 66 20 5b 73 71  n_v2()].  If [sq
63e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
63f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
6400: 28 29 5d 0a 2a 2a 20 69 73 20 75 73 65 64 2c 20  ()].** is used, 
6410: 74 68 65 6e 20 66 6c 61 67 73 20 69 73 20 5b 53  then flags is [S
6420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
6430: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
6440: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a  OPEN_CREATE]..**
6450: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
6460: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
6470: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
6480: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
6490: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
64a0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
64b0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
64c0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
64d0: 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a  e.** set..** .**
64e0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
64f0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
6500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
6510: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
6520: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
6530: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
6540: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
6550: 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  * .** <ul>.** <l
6560: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
6570: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
6580: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6590: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
65a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
65b0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
65c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
65d0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
65e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
65f0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6600: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
6610: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6620: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
6630: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
6640: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
6650: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
6660: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
6670: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
6680: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
6690: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
66a0: 67 65 73 20 74 68 65 20 77 61 79 20 69 74 20 64  ges the way it d
66b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
66c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
66d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
66e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
66f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
6700: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
6710: 62 61 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65  back, might make
6720: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
6730: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
6740: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
6750: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
6760: 61 72 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f  are.** also a no
6770: 2d 6f 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  -op.  Any attemp
6780: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
6790: 75 72 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c  urnal return SQL
67a0: 49 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72  ITE_IOERR..** Or
67b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
67c0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
67d0: 69 7a 65 20 74 68 65 20 61 20 64 61 74 61 62 61  ize the a databa
67e0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20  se file will.** 
67f0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
6800: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
6810: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
6820: 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a   a random order.
6830: 2a 2a 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  ** and set up it
6840: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
6850: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20  accordingly..** 
6860: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
6870: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
6880: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
6890: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
68a0: 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20  n.** method:.** 
68b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
68c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
68d0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
68e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
68f0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
6900: 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  </ul>.** .** The
6910: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
6920: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
6930: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
6940: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
6950: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
6960: 20 63 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77   closed.  This w
6970: 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65  ill always be se
6980: 74 20 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64  t for TEMP .** d
6990: 61 74 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75  atabases and jou
69a0: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
69b0: 62 6a 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20  bjournals.  The 
69c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
69d0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
69e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
69f0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
6a00: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
6a10: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
6a20: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
6a30: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
6a40: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
6a50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
6a60: 2a 2a 20 0a 2a 2a 20 53 70 61 63 65 20 74 6f 20  ** .** Space to 
6a70: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
6a80: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
6a90: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
6aa0: 20 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d   third .** argum
6ab0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ent to xOpen is 
6ac0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 63 61 6c  allocated by cal
6ad0: 6c 65 72 20 28 74 68 65 20 53 51 4c 69 74 65 20  ler (the SQLite 
6ae0: 63 6f 72 65 29 2e 20 0a 2a 2a 20 73 7a 4f 73 46  core). .** szOsF
6af0: 69 6c 65 20 62 79 74 65 73 20 61 72 65 20 61 6c  ile bytes are al
6b00: 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 69 73  located for this
6b10: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 78 4f   object.  The xO
6b20: 70 65 6e 20 6d 65 74 68 6f 64 0a 2a 2a 20 66 69  pen method.** fi
6b30: 6c 6c 73 20 69 6e 20 74 68 65 20 61 6c 6c 6f 63  lls in the alloc
6b40: 61 74 65 64 20 73 70 61 63 65 2e 0a 2a 2a 20 0a  ated space..** .
6b50: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6b60: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
6b70: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
6b80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
6b90: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
6ba0: 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20 6f   the existance o
6bb0: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
6bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
6bd0: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
6be0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
6bf0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
6c00: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
6c10: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
6c20: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
6c30: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
6c40: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
6c50: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
6c60: 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a  ile can be a .**
6c70: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a   directory..** .
6c80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
6c90: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
6ca0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
6cb0: 6d 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a 2a  me+1 byte for.**
6cc0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
6cd0: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
6ce0: 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  name and xFullPa
6cf0: 74 68 6e 61 6d 65 2e 20 54 68 65 20 65 78 61 63  thname. The exac
6d00: 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
6d10: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69   output buffer i
6d20: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
6d30: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
6d40: 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73  both .** methods
6d50: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
6d60: 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61  buffer is not la
6d70: 72 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49  rge enough, SQLI
6d80: 54 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73  TE_CANTOPEN.** s
6d90: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
6da0: 64 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61  d. As this is ha
6db0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
6dc0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
6dd0: 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65  ,.** vfs impleme
6de0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
6df0: 65 6e 64 65 76 6f 75 72 20 74 6f 20 70 72 65 76  endevour to prev
6e00: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
6e10: 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61  ing .** mxPathna
6e20: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
6e30: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
6e40: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
6e50: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
6e60: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
6e70: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
6e80: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
6e90: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
6ea0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
6eb0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
6ec0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
6ed0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
6ee0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
6ef0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
6f00: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
6f10: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
6f20: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
6f30: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
6f40: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
6f50: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
6f60: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
6f70: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
6f80: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
6f90: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
6fa0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65  ed.  The.** xSle
6fb0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
6fc0: 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  e the calling th
6fd0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
6fe0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
6ff0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
7000: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
7010: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
7020: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
7030: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
7040: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
7050: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
7060: 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74  nd.** time..*/.t
7070: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7080: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
7090: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
70a0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
70b0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
70c0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
70d0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
70e0: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
70f0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
7100: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
7110: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
7120: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
7130: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
7140: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
7150: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
7160: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
7170: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
7180: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
7190: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
71a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
71b0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
71c0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
71d0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
71e0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
71f0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
7200: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
7210: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
7220: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
7230: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
7240: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
7250: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
7260: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
7270: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
7280: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
7290: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
72a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
72b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
72c0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
72d0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
72e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
72f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
7300: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
7310: 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28  (*xGetTempname)(
7320: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
7330: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
7340: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
7350: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
7360: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
7370: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
7380: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
7390: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
73a0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
73b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
73c0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
73d0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
73e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
73f0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
7400: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
7410: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
7420: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
7430: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
7440: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
7450: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
7460: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
7470: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
7480: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
7490: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
74a0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
74b0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
74c0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
74d0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
74e0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
74f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
7500: 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  uble*);.  /* New
7510: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7520: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
7530: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
7540: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
7550: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
7560: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
7570: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
7580: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7590: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
75a0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
75b0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
75c0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
75d0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
75e0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
75f0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
7600: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
7610: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
7620: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
7630: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
7640: 6b 69 6e 64 20 6f 66 20 77 68 61 74 20 6b 69 6e  kind of what kin
7650: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
7660: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
7670: 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e  hod is.** lookin
7680: 67 20 66 6f 72 2e 20 20 57 69 74 68 20 53 51 4c  g for.  With SQL
7690: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
76a0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
76b0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
76c0: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66  checks to see if
76d0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
76e0: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
76f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
7700: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
7710: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f  method checks to
7720: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
7730: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
7740: 65 0a 2a 2a 20 61 6e 64 20 77 72 69 74 61 62 6c  e.** and writabl
7750: 65 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f  e.  With SQLITE_
7760: 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65 20  ACCESS_READ the 
7770: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
7780: 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  * checks to see 
7790: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  if the file is r
77a0: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
77b0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
77c0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
77d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
77e0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
77f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7800: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
7810: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
7820: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
7830: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
7840: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
7850: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
7860: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
7870: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
7880: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
7890: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
78a0: 64 65 73 5d 20 66 65 61 74 75 72 65 2e 0a 2a 2a  des] feature..**
78b0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c   By default, SQL
78c0: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
78d0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 6f   return one of o
78e0: 6e 6c 79 20 32 36 20 69 6e 74 65 67 65 72 0a 2a  nly 26 integer.*
78f0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
7900: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 57  esult codes].  W
7910: 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
7920: 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65  ult codes.** are
7930: 20 65 6e 61 62 6c 65 64 20 62 79 20 74 68 69 73   enabled by this
7940: 20 72 6f 75 74 69 6e 65 2c 20 74 68 65 20 72 65   routine, the re
7950: 70 65 74 6f 69 72 65 20 6f 66 20 72 65 73 75 6c  petoire of resul
7960: 74 20 63 6f 64 65 73 20 63 61 6e 20 62 65 0a 2a  t codes can be.*
7970: 2a 20 6d 75 63 68 20 6c 61 72 67 65 72 20 61 6e  * much larger an
7980: 64 20 63 61 6e 20 28 68 6f 70 65 66 75 6c 6c 79  d can (hopefully
7990: 29 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  ) provide more d
79a0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
79b0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ion.** about the
79c0: 20 63 61 75 73 65 20 6f 66 20 61 6e 20 65 72 72   cause of an err
79d0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  or..**.** The se
79e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
79f0: 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c 75 65   a boolean value
7a00: 20 74 68 61 74 20 74 75 72 6e 73 20 65 78 74 65   that turns exte
7a10: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
7a20: 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  odes on and off.
7a30: 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c    Extended resul
7a40: 74 20 63 6f 64 65 73 20 61 72 65 20 6f 66 66 20  t codes are off 
7a50: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a  by default for.*
7a60: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
7a70: 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
7a80: 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lder versions of
7a90: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
7aa0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
7ab0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
7ac0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
7ad0: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
7ae0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
7af0: 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 45 61 63   Rowid.**.** Eac
7b00: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
7b10: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
7b20: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
7b30: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 6b 65  igned integer ke
7b40: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 68 65 20  y.** called the 
7b50: 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77  "rowid". The row
7b60: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
7b70: 69 6c 61 62 6c 65 20 61 73 20 61 6e 20 75 6e 64  ilable as an und
7b80: 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f 6c 75 6d  eclared.** colum
7b90: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
7ba0: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 2e 20  ID, or _ROWID_. 
7bb0: 20 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61   If the table ha
7bc0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a  s a column of.**
7bd0: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52   type INTEGER PR
7be0: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74  IMARY KEY then t
7bf0: 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 61 6e  hat column is an
7c00: 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 73 20 66  other an alias f
7c10: 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77 69 64 2e  or the.** rowid.
7c20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
7c30: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
7c40: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
7c50: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 20  t recent INSERT 
7c60: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61  into.** the data
7c70: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
7c80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7c90: 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66  n given in the f
7ca0: 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  irst .** argumen
7cb0: 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73 65 72 74  t.  If no insert
7cc0: 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
7cd0: 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74  rred on this dat
7ce0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
7cf0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
7d00: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
7d10: 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73  an INSERT occurs
7d20: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
7d30: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69  r, then the rowi
7d40: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65  d of the.** inse
7d50: 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75  rted row is retu
7d60: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
7d70: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
7d80: 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69  the trigger.** i
7d90: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20  s running.  But 
7da0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
7db0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
7dc0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
7dd0: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
7de0: 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ne reverts to th
7df0: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
7e00: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
7e10: 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65  .** trigger fire
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 64 6f 65 73 20  her thread does 
7e40: 61 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20  a new insert on 
7e50: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
7e60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
7e70: 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
7e80: 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  ne is running an
7e90: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
7ea0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
7eb0: 6f 77 69 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  owid,.** then th
7ec0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
7ed0: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
7ee0: 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
7ef0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
7f00: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
7f10: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
7f20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
7f30: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
7f40: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
7f50: 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ified.**.** This
7f60: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
7f70: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
7f80: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
7f90: 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
7fa0: 2a 2a 20 28 6f 72 20 69 6e 73 65 72 74 65 64 20  ** (or inserted 
7fb0: 6f 72 20 64 65 6c 65 74 65 64 29 20 62 79 20 74  or deleted) by t
7fc0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 53  he most recent S
7fd0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f  QL statement.  O
7fe0: 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  nly.** changes t
7ff0: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
8000: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
8010: 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
8020: 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73  , or.** DELETE s
8030: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
8040: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
8050: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
8060: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61  by.** triggers a
8070: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
8080: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
8090: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
80a0: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
80b0: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
80c0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
80d0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
80e0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
80f0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57  riggers..**.** W
8100: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
8110: 66 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  f a trigger, the
8120: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
8130: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
8140: 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f   be.** called to
8150: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
8160: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
8170: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
8180: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
8190: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
81a0: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
81b0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
81c0: 62 6f 64 79 20 6f 66 20 74 68 65 20 74 72 69 67  body of the trig
81d0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63  ger..**.** All c
81e0: 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
81f0: 65 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79  ed, even if they
8200: 20 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f   were later undo
8210: 6e 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42  ne by a.** ROLLB
8220: 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 45  ACK or ABORT.  E
8230: 78 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61  xcept, changes a
8240: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
8250: 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64  reating and.** d
8260: 72 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61  ropping tables a
8270: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
8280: 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62  **.** If a callb
8290: 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ack invokes [sql
82a0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
82b0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
82c0: 20 72 65 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a   recursively,.**
82d0: 20 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65   then the change
82e0: 73 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20  s in the inner, 
82f0: 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61  recursive call a
8300: 72 65 20 63 6f 75 6e 74 65 64 20 74 6f 67 65 74  re counted toget
8310: 68 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  her.** with the 
8320: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f  changes in the o
8330: 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  uter call..**.**
8340: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
8350: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
8360: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
8370: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
8380: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
8390: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
83a0: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
83b0: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
83c0: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
83d0: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
83e0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
83f0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
8400: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
8410: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
8420: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
8430: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
8440: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
8450: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
8460: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
8470: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
8480: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
8490: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
84a0: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
84b0: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
84c0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
84d0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
84e0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
84f0: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
8500: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
8510: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
8520: 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
8530: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
8540: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
8550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8560: 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72  .** while this r
8570: 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
8580: 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  g then the retur
8590: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
85a0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e  routine.** is un
85b0: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
85c0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
85d0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
85e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
85f0: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
8600: 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a 2a   Modified.***.**
8610: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
8620: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
8630: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
8640: 77 73 20 74 68 61 74 20 68 61 76 65 20 62 65 65  ws that have bee
8650: 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62 79  n.** modified by
8660: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
8670: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
8680: 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64  ents since the d
8690: 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a  atabase handle.*
86a0: 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 54 68  * was opened. Th
86b0: 69 73 20 69 6e 63 6c 75 64 65 73 20 55 50 44 41  is includes UPDA
86c0: 54 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 44  TE, INSERT and D
86d0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
86e0: 20 65 78 65 63 75 74 65 64 0a 2a 2a 20 61 73 20   executed.** as 
86f0: 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
8700: 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20 63 68  programs. All ch
8710: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
8720: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
8730: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
8740: 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
8750: 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
8760: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
8770: 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61 73 73  andle is.** pass
8780: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
8790: 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
87a0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
87b0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
87c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
87d0: 61 6e 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63  ange()] interfac
87e0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e..**.** SQLite 
87f0: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
8800: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
8810: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
8820: 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  ut a WHERE claus
8830: 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67  e.** by dropping
8840: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
8850: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
8860: 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72  s is much faster
8870: 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74   than going.** t
8880: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
8890: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
88a0: 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65  lements form the
88b0: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73   table.)  Becaus
88c0: 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74  e of.** this opt
88d0: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63  imization, the c
88e0: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20  hange count for 
88f0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
8900: 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a  le" will be.** z
8910: 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ero regardless o
8920: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
8930: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
8940: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  re originally in
8950: 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54   the.** table. T
8960: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74  o get an accurat
8970: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  e count of the n
8980: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65  umber of rows de
8990: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44  leted, use.** "D
89a0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
89b0: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61   WHERE 1" instea
89c0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  d..**.** If anot
89d0: 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 73  her thread makes
89e0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
89f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
8a00: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
8a10: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
8a20: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
8a30: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
8a40: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  of this routine.
8a50: 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
8a60: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
8a70: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
8a80: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
8a90: 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
8aa0: 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
8ab0: 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54  ng Query.**.** T
8ac0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
8ad0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
8ae0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
8af0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
8b00: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
8b10: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
8b20: 75 6e 69 74 79 2e 20 20 54 68 69 73 20 72 6f 75  unity.  This rou
8b30: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
8b40: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
8b50: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
8b60: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
8b70: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
8b80: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
8b90: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
8ba0: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
8bb0: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
8bc0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
8bd0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
8be0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
8bf0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
8c00: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
8c10: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
8c20: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
8c30: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
8c40: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
8c50: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
8c60: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
8c70: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
8c80: 6e 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ne with a databa
8c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
8ca0: 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
8cb0: 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
8cc0: 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
8cd0: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
8ce0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
8cf0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
8d00: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
8d10: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
8d20: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
8d30: 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 72 75 70  * If an interrup
8d40: 74 65 64 20 6f 70 65 72 61 74 69 6f 6e 20 77 61  ted operation wa
8d50: 73 20 61 6e 20 75 70 64 61 74 65 20 74 68 61 74  s an update that
8d60: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a   is inside an.**
8d70: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
8d80: 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
8d90: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
8da0: 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  on will be rolle
8db0: 64 0a 2a 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61  d.** back automa
8dc0: 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64  tically..*/.void
8dd0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
8de0: 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
8df0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
8e00: 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
8e10: 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
8e20: 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
8e30: 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
8e40: 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
8e50: 65 20 67 69 76 65 6e 20 69 6e 70 75 74 20 73 74  e given input st
8e60: 72 69 6e 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a  ring comprises.*
8e70: 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f  * one or more co
8e80: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
8e90: 6d 65 6e 74 73 2e 20 46 6f 72 20 74 68 65 20 73  ments. For the s
8ea0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
8eb0: 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70  ) call,.** the p
8ec0: 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
8ed0: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
8ee0: 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 20  d UTF-8 string. 
8ef0: 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  For.** sqlite3_c
8f00: 6f 6d 70 6c 65 74 65 31 36 28 29 2c 20 61 20 6e  omplete16(), a n
8f10: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 6d 61  ul-terminated ma
8f20: 63 68 69 6e 65 20 62 79 74 65 20 6f 72 64 65 72  chine byte order
8f30: 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
8f40: 2a 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  * is required..*
8f50: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
8f60: 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66  nes are useful f
8f70: 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  or command-line 
8f80: 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
8f90: 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
8fa0: 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
8fb0: 65 78 74 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72  ext forms one or
8fc0: 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53   more complete S
8fd0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  QL statements or
8fe0: 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
8ff0: 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
9000: 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
9010: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
9020: 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
9030: 6f 72 20 70 61 72 73 69 6e 67 2e 20 54 68 65 20  or parsing. The 
9040: 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 73 69 6d  algorithm is sim
9050: 70 6c 65 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a  ple.  If the .**
9060: 20 6c 61 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65   last token othe
9070: 72 20 74 68 61 6e 20 73 70 61 63 65 73 20 61 6e  r than spaces an
9080: 64 20 63 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20  d comments is a 
9090: 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20  semicolon, then 
90a0: 72 65 74 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e  return .** true.
90b0: 20 20 41 63 74 75 61 6c 6c 79 2c 20 74 68 65 20    Actually, the 
90c0: 61 6c 67 6f 72 69 74 68 6d 20 69 73 20 61 20 6c  algorithm is a l
90d0: 69 74 74 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  ittle more compl
90e0: 69 63 61 74 65 64 20 74 68 61 6e 20 74 68 61 74  icated than that
90f0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
9100: 64 65 61 6c 20 77 69 74 68 20 74 72 69 67 67 65  deal with trigge
9110: 72 73 2c 20 62 75 74 20 74 68 65 20 62 61 73 69  rs, but the basi
9120: 63 20 69 64 65 61 20 69 73 20 74 68 65 20 73 61  c idea is the sa
9130: 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 73 74 61 74  me:  the.** stat
9140: 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d  ement is not com
9150: 70 6c 65 74 65 20 75 6e 6c 65 73 73 20 69 74 20  plete unless it 
9160: 65 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f  ends in a semico
9170: 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  lon..*/.int sqli
9180: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
9190: 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
91a0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
91b0: 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
91c0: 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
91d0: 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
91e0: 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
91f0: 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
9200: 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
9210: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65  This routine ide
9220: 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61  ntifies a callba
9230: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
9240: 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
9250: 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 6e  d.** whenever an
9260: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
9270: 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
9280: 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68  ase table .** th
9290: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
92a0: 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  d or process has
92b0: 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74   locked..** If t
92c0: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
92d0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
92e0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
92f0: 28 6f 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53  (or sometimes [S
9300: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
9310: 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75  KED]).** is retu
9320: 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
9330: 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
9340: 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  ng the lock..** 
9350: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
9360: 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  back is not NULL
9370: 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61  , then the.** ca
9380: 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
9390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
93a0: 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a  arguments.  The.
93b0: 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  ** first argumen
93c0: 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72  t to the handler
93d0: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
93e0: 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
93f0: 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
9400: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
9410: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20  o this routine. 
9420: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
9430: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
9440: 61 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75  andler is the nu
9450: 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
9460: 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
9470: 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
9480: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
9490: 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
94a0: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
94b0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
94c0: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
94d0: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
94e0: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
94f0: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
9500: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
9510: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
9520: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
9530: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
9540: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
9550: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
9560: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
9570: 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
9580: 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  open the.** data
9590: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
95a0: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
95b0: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
95c0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
95d0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
95e0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
95f0: 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20  that.** it will 
9600: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
9610: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
9620: 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20  ntention..** If 
9630: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
9640: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
9650: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
9660: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
9670: 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20  .** a deadlock, 
9680: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  it will return [
9690: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 6e 73  SQLITE_BUSY] ins
96a0: 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  tead..** Conside
96b0: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
96c0: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
96d0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
96e0: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
96f0: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
9700: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
9710: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
9720: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
9730: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
9740: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
9750: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
9760: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
9770: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
9780: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
9790: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
97a0: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
97b0: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
97c0: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
97d0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
97e0: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
97f0: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
9800: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
9810: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
9820: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
9830: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
9840: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
9850: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
9860: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
9870: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
9880: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
9890: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
98a0: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
98b0: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
98c0: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
98d0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
98e0: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
98f0: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
9900: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
9910: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
9930: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
9940: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
9950: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
9960: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
9970: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
9980: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
9990: 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  when.** SQLite i
99a0: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
99b0: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
99c0: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
99d0: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
99e0: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
99f0: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
9a00: 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
9a10: 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
9a20: 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
9a30: 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
9a40: 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
9a50: 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
9a60: 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
9a70: 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
9a80: 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
9a90: 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
9aa0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
9ab0: 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
9ac0: 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
9ad0: 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
9ae0: 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
9af0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
9b00: 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
9b10: 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
9b20: 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
9b30: 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
9b40: 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
9b50: 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
9b60: 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
9b70: 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
9b80: 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
9b90: 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
9ba0: 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
9bb0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
9bc0: 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
9bd0: 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
9be0: 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
9bf0: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
9c00: 74 68 65 20 63 68 61 6e 67 65 73 2e 20 53 65 65  the changes. See
9c10: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
9c20: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
9c30: 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77  te.org/cvstrac/w
9c40: 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
9c50: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
9c60: 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
9c70: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
9c80: 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
9c90: 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
9ca0: 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
9cb0: 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
9cc0: 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69  .**..** Sqlite i
9cd0: 73 20 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f  s re-entrant, so
9ce0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
9cf0: 72 20 6d 61 79 20 73 74 61 72 74 20 61 20 6e 65  r may start a ne
9d00: 77 20 71 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74  w query. .** (It
9d10: 20 69 73 20 6e 6f 74 20 63 6c 65 61 72 20 77 68   is not clear wh
9d20: 79 20 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65  y anyone would e
9d30: 76 65 72 79 20 77 61 6e 74 20 74 6f 20 64 6f 20  very want to do 
9d40: 74 68 69 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20  this, but it.** 
9d50: 69 73 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74  is allowed, in t
9d60: 68 65 6f 72 79 2e 29 20 20 42 75 74 20 74 68 65  heory.)  But the
9d70: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61   busy handler ma
9d80: 79 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a  y not close the.
9d90: 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 43 6c  ** database.  Cl
9da0: 6f 73 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  osing the databa
9db0: 73 65 20 66 72 6f 6d 20 61 20 62 75 73 79 20 68  se from a busy h
9dc0: 61 6e 64 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65  andler will dele
9dd0: 74 65 20 0a 2a 2a 20 64 61 74 61 20 73 74 72 75  te .** data stru
9de0: 63 74 75 72 65 73 20 6f 75 74 20 66 72 6f 6d 20  ctures out from 
9df0: 75 6e 64 65 72 20 74 68 65 20 65 78 65 63 75 74  under the execut
9e00: 69 6e 67 20 71 75 65 72 79 20 61 6e 64 20 77 69  ing query and wi
9e10: 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20  ll .** probably 
9e20: 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
9e30: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
9e40: 72 20 6f 74 68 65 72 20 72 75 6e 74 69 6d 65 20  r other runtime 
9e50: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
9e60: 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
9e70: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
9e80: 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
9e90: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a   each database.*
9ea0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9eb0: 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
9ec0: 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
9ed0: 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e   any previous on
9ee0: 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
9ef0: 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
9f00: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
9f10: 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
9f20: 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62  r clear.** the b
9f30: 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
9f40: 2a 2a 20 57 68 65 6e 20 6f 70 65 72 61 74 69 6e  ** When operatin
9f50: 67 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 65 6e  g in [sqlite3_en
9f60: 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
9f70: 65 20 7c 20 73 68 61 72 65 64 20 63 61 63 68 65  e | shared cache
9f80: 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20   mode],.** only 
9f90: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
9fa0: 6e 64 6c 65 72 20 63 61 6e 20 62 65 20 64 65 66  ndler can be def
9fb0: 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61  ined for each da
9fc0: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20  tabase file..** 
9fd0: 53 6f 20 69 66 20 74 77 6f 20 64 61 74 61 62 61  So if two databa
9fe0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73  se connections s
9ff0: 68 61 72 65 20 61 20 73 69 6e 67 6c 65 20 63 61  hare a single ca
a000: 63 68 65 2c 20 74 68 65 6e 20 63 68 61 6e 67 69  che, then changi
a010: 6e 67 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  ng.** the busy h
a020: 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e 65 20 63 6f  andler on one co
a030: 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  nnection will al
a040: 73 6f 20 63 68 61 6e 67 65 20 74 68 65 20 62 75  so change the bu
a050: 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 6e  sy.** handler in
a060: 20 74 68 65 20 6f 74 68 65 72 20 63 6f 6e 6e 65   the other conne
a070: 63 74 69 6f 6e 2e 20 20 54 68 65 20 62 75 73 79  ction.  The busy
a080: 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f   handler is invo
a090: 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 65 20 74 68  ked.** in the th
a0a0: 72 65 61 64 20 74 68 61 74 20 77 61 73 20 72 75  read that was ru
a0b0: 6e 6e 69 6e 67 20 77 68 65 6e 20 74 68 65 20 53  nning when the S
a0c0: 51 4c 49 54 45 5f 42 55 53 59 20 77 61 73 20 68  QLITE_BUSY was h
a0d0: 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  it..*/.int sqlit
a0e0: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
a0f0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
a100: 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
a110: 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
a120: 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
a130: 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54   Timeout.**.** T
a140: 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
a150: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
a160: 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20  that sleeps for 
a170: 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a  a while when a.*
a180: 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  * table is locke
a190: 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20  d.  The handler 
a1a0: 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
a1b0: 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
a1c0: 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73  .** at least "ms
a1d0: 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
a1e0: 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20  f sleeping have 
a1f0: 62 65 65 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65  been done.  Afte
a200: 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73  r.** "ms" millis
a210: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
a220: 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20  ng, the handler 
a230: 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a  returns 0 which.
a240: 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ** causes [sqlit
a250: 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
a260: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
a270: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
a280: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
a290: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
a2a0: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
a2b0: 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
a2c0: 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
a2d0: 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
a2e0: 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
a2f0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
a300: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
a310: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
a320: 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
a330: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
a340: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20  connection.  If 
a350: 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
a360: 64 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64  dler was defined
a370: 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71    .** (using [sq
a380: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
a390: 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
a3a0: 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
a3b0: 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
a3c0: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
a3d0: 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a   is cleared..*/.
a3e0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
a3f0: 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
a400: 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
a410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
a420: 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
a430: 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
a440: 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
a450: 20 6e 65 78 74 20 72 6f 75 74 69 6e 65 20 69 73   next routine is
a460: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
a470: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 5b 73  rapper around [s
a480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a  qlite3_exec()]..
a490: 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e  ** Instead of in
a4a0: 76 6f 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75  voking a user-su
a4b0: 70 70 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20  pplied callback 
a4c0: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
a4d0: 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74  the.** result, t
a4e0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65  his routine reme
a4f0: 6d 62 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f  mbers each row o
a500: 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  f the result in 
a510: 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e  memory.** obtain
a520: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a530: 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e  _malloc()], then
a540: 20 72 65 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20   returns all of 
a550: 74 68 65 20 72 65 73 75 6c 74 20 61 66 74 65 72  the result after
a560: 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 68 61   the.** query ha
a570: 73 20 66 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a  s finished. .**.
a580: 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
a590: 2c 20 73 75 70 70 6f 73 65 20 74 68 65 20 71 75  , suppose the qu
a5a0: 65 72 79 20 72 65 73 75 6c 74 20 77 68 65 72 65  ery result where
a5b0: 20 74 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a   this table:.**.
a5c0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
a5d0: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
a5e0: 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
a5f0: 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
a600: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a610: 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
a620: 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
a630: 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
a640: 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
a650: 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
a660: 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
a670: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
a680: 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75   If the 3rd argu
a690: 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73  ment were &azRes
a6a0: 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74  ult then after t
a6b0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
a6c0: 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20  rns.** azResult 
a6d0: 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65  will contain the
a6e0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a   following data:
a6f0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
a700: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
a710: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a720: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
a730: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
a740: 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
a750: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
a760: 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
a770: 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
a780: 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
a790: 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
a7a0: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
a7b0: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
a7c0: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
a7d0: 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
a7e0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
a7f0: 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
a800: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a810: 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
a820: 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
a830: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
a840: 4e 6f 74 69 63 65 20 74 68 61 74 20 74 68 65 72  Notice that ther
a850: 65 20 69 73 20 61 6e 20 65 78 74 72 61 20 72 6f  e is an extra ro
a860: 77 20 6f 66 20 64 61 74 61 20 63 6f 6e 74 61 69  w of data contai
a870: 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a  ning the column.
a880: 2a 2a 20 68 65 61 64 65 72 73 2e 20 20 42 75 74  ** headers.  But
a890: 20 74 68 65 20 2a 6e 72 6f 77 20 72 65 74 75 72   the *nrow retur
a8a0: 6e 20 76 61 6c 75 65 20 69 73 20 73 74 69 6c 6c  n value is still
a8b0: 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73   3.  *ncolumn is
a8c0: 0a 2a 2a 20 73 65 74 20 74 6f 20 32 2e 20 20 49  .** set to 2.  I
a8d0: 6e 20 67 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e  n general, the n
a8e0: 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
a8f0: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 7a  inserted into az
a900: 52 65 73 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62  Result.** will b
a910: 65 20 28 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a  e ((*nrow) + 1)*
a920: 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a  (*ncolumn)..**.*
a930: 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
a940: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
a950: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
a960: 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
a970: 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74  hould .** pass t
a980: 68 65 20 72 65 73 75 6c 74 20 64 61 74 61 20 70  he result data p
a990: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
a9a0: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
a9b0: 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72  n order to .** r
a9c0: 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
a9d0: 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
a9e0: 63 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  c-ed.  Because o
a9f0: 66 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a  f the way the .*
aa00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
aa10: 63 28 29 5d 20 68 61 70 70 65 6e 73 2c 20 74 68  c()] happens, th
aa20: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
aa30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
aa40: 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c  to call .** [sql
aa50: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
aa60: 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71  ectly.  Only [sq
aa70: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
aa80: 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
aa90: 65 6c 65 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d  elease .** the m
aaa0: 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
aab0: 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
aac0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
aad0: 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
aae0: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
aaf0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 65   from [sqlite3_e
ab00: 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  xec()]..*/.int s
ab10: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
ab20: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
ab30: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
ab40: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
ab50: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
ab60: 73 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  sql,       /* SQ
ab70: 4c 20 74 6f 20 62 65 20 65 78 65 63 75 74 65 64  L to be executed
ab80: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65   */.  char ***re
ab90: 73 75 6c 74 70 2c 20 20 20 20 20 20 20 2f 2a 20  sultp,       /* 
aba0: 52 65 73 75 6c 74 20 77 72 69 74 74 65 6e 20 74  Result written t
abb0: 6f 20 61 20 63 68 61 72 20 2a 5b 5d 20 20 74 68  o a char *[]  th
abc0: 61 74 20 74 68 69 73 20 70 6f 69 6e 74 73 20 74  at this points t
abd0: 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77  o */.  int *nrow
abe0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ,             /*
abf0: 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
ac00: 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
ac10: 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63  ere */.  int *nc
ac20: 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 20  olumn,          
ac30: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
ac40: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
ac50: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
ac60: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
ac70: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
ac80: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
ac90: 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
aca0: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
acb0: 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
acc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
acd0: 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
ace0: 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
acf0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
ad00: 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61  utines are worka
ad10: 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
ad20: 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
ad30: 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
ad40: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ad50: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
ad60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70  * The sqlite3_mp
ad70: 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
ad80: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
ad90: 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
ada0: 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
adb0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
adc0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
add0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
ade0: 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
adf0: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
ae00: 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
ae10: 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
ae20: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
ae30: 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74  e()].  Both rout
ae40: 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
ae50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
ae60: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ae70: 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
ae80: 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
ae90: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
aea0: 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
aeb0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
aec0: 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
aed0: 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
aee0: 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
aef0: 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
af00: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
af10: 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
af20: 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
af30: 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
af40: 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
af50: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
af60: 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
af70: 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
af80: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
af90: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
afa0: 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
afb0: 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
afc0: 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
afd0: 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
afe0: 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
aff0: 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
b000: 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
b010: 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
b020: 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
b030: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
b040: 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
b050: 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
b060: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
b070: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
b080: 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
b090: 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
b0a0: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
b0b0: 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
b0c0: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
b0d0: 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
b0e0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
b0f0: 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
b100: 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
b110: 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
b120: 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
b130: 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
b140: 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
b150: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
b160: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
b170: 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
b180: 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
b190: 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
b1a0: 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
b1b0: 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
b1c0: 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
b1d0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
b1e0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
b1f0: 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
b200: 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
b210: 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
b220: 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
b230: 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
b240: 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
b250: 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
b260: 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
b270: 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
b280: 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
b290: 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
b2a0: 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
b2b0: 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
b2c0: 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
b2d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
b2e0: 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
b2f0: 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
b300: 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
b310: 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
b320: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
b330: 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
b340: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
b350: 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
b360: 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69   printf formatti
b370: 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
b380: 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
b390: 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
b3a0: 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
b3b0: 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
b3c0: 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
b3d0: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
b3e0: 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
b3f0: 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
b400: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
b410: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
b420: 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
b430: 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
b440: 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
b450: 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
b460: 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
b470: 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
b480: 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
b490: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
b4a0: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
b4b0: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
b4c0: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
b4d0: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
b4e0: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
b4f0: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
b500: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
b510: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
b520: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
b530: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
b540: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b550: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
b560: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
b570: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
b580: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
b590: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
b5a0: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
b5b0: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
b5c0: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
b5d0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
b5e0: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
b5f0: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
b600: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
b610: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
b620: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
b630: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
b640: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
b650: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
b660: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
b670: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
b680: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
b690: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
b6a0: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
b6b0: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
b6c0: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
b6d0: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
b6e0: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
b6f0: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
b700: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b710: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
b720: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
b730: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
b740: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
b750: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
b760: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
b770: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
b780: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
b790: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
b7a0: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
b7b0: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
b7c0: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
b7d0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
b7e0: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
b7f0: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
b800: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
b810: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
b820: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
b830: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
b840: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
b850: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
b860: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
b870: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
b880: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
b890: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
b8a0: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
b8b0: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
b8c0: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
b8d0: 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
b8e0: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
b8f0: 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
b900: 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
b910: 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
b920: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
b930: 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20  tal string.  Or 
b940: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
b950: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
b960: 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55  .** list is a NU
b970: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
b980: 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
b990: 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
b9a0: 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75  out single.** qu
b9b0: 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
b9c0: 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
b9d0: 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
b9e0: 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
b9f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
ba00: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
ba10: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
ba20: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
ba30: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
ba40: 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
ba50: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
ba60: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
ba70: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
ba80: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
ba90: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
baa0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
bab0: 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
bac0: 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
bad0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
bae0: 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
baf0: 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
bb00: 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
bb10: 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
bb20: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
bb30: 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
bb40: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
bb50: 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
bb60: 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
bb70: 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
bb80: 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
bb90: 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
bba0: 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
bbb0: 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
bbc0: 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
bbd0: 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
bbe0: 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68 61 72 20 2a  tring..*/.char *
bbf0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
bc00: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
bc10: 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
bc20: 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
bc30: 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
bc40: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
bc50: 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
bc60: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
bc70: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
bc80: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
bc90: 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
bca0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
bcb0: 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
bcc0: 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
bcd0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
bce0: 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
bcf0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
bd00: 6e 20 6e 65 65 64 73 2e 20 28 53 65 65 20 74 68  n needs. (See th
bd10: 65 20 65 78 63 65 70 74 69 6f 6e 20 62 65 6c 6f  e exception belo
bd20: 77 2e 29 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  w.).** The defau
bd30: 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  lt implementatio
bd40: 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f  n.** of the memo
bd50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
bd60: 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65  bsystem uses the
bd70: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
bd80: 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65  oc().** and free
bd90: 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
bda0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
bdb0: 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65 72 2c  brary.  However,
bdc0: 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69   if .** SQLite i
bdd0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
bde0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20  the following C 
bdf0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
be00: 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  ro.**.** <blockq
be10: 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4f 4d 49  uote> SQLITE_OMI
be20: 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
be30: 49 4f 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  ION </blockquote
be40: 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20  >.**.** then no 
be50: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
be60: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 74  s provided for t
be70: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 62 79  hese routines by
be80: 0a 2a 2a 20 53 51 4c 69 74 65 2e 20 20 54 68 65  .** SQLite.  The
be90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
bea0: 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
beb0: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 65 78 70  SQLite is.** exp
bec0: 65 63 74 65 64 20 74 6f 20 70 72 6f 76 69 64 65  ected to provide
bed0: 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 6d 65   its own impleme
bee0: 6e 74 61 74 69 6f 6e 2e 20 20 49 66 20 74 68 65  ntation.  If the
bef0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
bf00: 64 6f 65 73 20 70 72 6f 76 69 64 65 20 69 74 73  does provide its
bf10: 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74   own implementat
bf20: 69 6f 6e 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ion for these ro
bf30: 75 74 69 6e 65 73 2c 20 74 68 65 6e 0a 2a 2a 20  utines, then.** 
bf40: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 70 72 6f  it must also pro
bf50: 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  vide an implemen
bf60: 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 5b  tations for.** [
bf70: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
bf80: 6c 61 72 6d 28 29 5d 2c 20 5b 73 71 6c 69 74 65  larm()], [sqlite
bf90: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
bfa0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
bfb0: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
bfc0: 65 72 28 29 5d 2e 20 20 54 68 65 20 61 6c 74 65  er()].  The alte
bfd0: 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
bfe0: 74 61 74 69 6f 6e 73 0a 2a 2a 20 66 6f 72 20 74  tations.** for t
bff0: 68 65 73 65 20 6c 61 73 74 20 74 68 72 65 65 20  hese last three 
c000: 72 6f 75 74 69 6e 65 73 20 6e 65 65 64 20 6e 6f  routines need no
c010: 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2c  t actually work,
c020: 20 62 75 74 0a 2a 2a 20 73 74 75 62 20 66 75 6e   but.** stub fun
c030: 63 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ctions at least 
c040: 61 72 65 20 6e 65 65 64 65 64 20 74 6f 20 73 74  are needed to st
c050: 61 74 69 73 66 79 20 74 68 65 20 6c 69 6e 6b 65  atisfy the linke
c060: 72 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 65 76  r..** SQLite nev
c070: 65 72 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  er calls [sqlite
c080: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
c090: 65 72 28 29 5d 20 69 74 73 65 6c 66 2c 20 62 75  er()] itself, bu
c0a0: 74 0a 2a 2a 20 74 68 65 20 73 79 6d 62 6f 6c 20  t.** the symbol 
c0b0: 69 73 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 61  is included in a
c0c0: 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f   table as part o
c0d0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
c0e0: 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
c0f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
c100: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
c110: 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20  memory_alarm()] 
c120: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  and [sqlite3_mem
c130: 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 6e 74 65  ory_used()] inte
c140: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 63 61  rfaces.** are ca
c150: 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  lled by [sqlite3
c160: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
c170: 28 29 5d 20 61 6e 64 20 77 6f 72 6b 69 6e 67 20  ()] and working 
c180: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
c190: 2a 2a 20 6f 66 20 62 6f 74 68 20 72 6f 75 74 69  ** of both routi
c1a0: 6e 65 73 20 6d 75 73 74 20 62 65 20 70 72 6f 76  nes must be prov
c1b0: 69 64 65 64 20 69 66 20 5b 73 71 6c 69 74 65 33  ided if [sqlite3
c1c0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
c1d0: 28 29 5d 0a 2a 2a 20 69 73 20 74 6f 20 6f 70 65  ()].** is to ope
c1e0: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 2e 0a  rate correctly..
c1f0: 2a 2a 0a 2a 2a 20 3c 62 3e 45 78 63 65 70 74 69  **.** <b>Excepti
c200: 6f 6e 3a 3c 2f 62 3e 20 54 68 65 20 77 69 6e 64  on:</b> The wind
c210: 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
c220: 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
c230: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
c240: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
c250: 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
c260: 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
c270: 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
c280: 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
c290: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
c2a0: 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
c2b0: 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
c2c0: 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
c2d0: 70 61 72 74 69 63 75 6c 61 72 20 77 69 6e 64 6f  particular windo
c2e0: 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
c2f0: 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
c300: 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
c310: 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
c320: 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
c330: 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
c340: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
c350: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
c360: 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
c370: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
c380: 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
c390: 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
c3a0: 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
c3b0: 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
c3c0: 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
c3d0: 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
c3e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
c3f0: 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
c400: 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e  tistics.**.** In
c410: 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 74 68 65   addition to the
c420: 20 62 61 73 69 63 20 74 68 72 65 65 20 61 6c 6c   basic three all
c430: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c440: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
c450: 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
c460: 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
c470: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
c480: 29 5d 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  )],.** the memor
c490: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
c4a0: 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20  system included 
c4b0: 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 0a  with the SQLite.
c4c0: 2a 2a 20 73 6f 75 72 63 65 73 20 70 72 6f 76 69  ** sources provi
c4d0: 64 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  des the interfac
c4e0: 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  es shown below..
c4f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
c500: 6f 66 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  of these two rou
c510: 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 74 68  tines returns th
c520: 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  e amount of memo
c530: 72 79 20 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  ry .** currently
c540: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
c550: 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
c560: 72 65 65 64 29 2e 20 20 54 68 65 20 73 65 63 6f  reed).  The seco
c570: 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  nd.** returns th
c580: 65 20 6c 61 72 67 65 73 74 20 69 6e 73 74 61 6e  e largest instan
c590: 74 61 6e 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f  taneous amount o
c5a0: 66 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a  f outstanding.**
c5b0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 68 69   memory.  The hi
c5c0: 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  ghwater mark is 
c5d0: 72 65 73 65 74 20 69 66 20 74 68 65 20 61 72 67  reset if the arg
c5e0: 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65  ument is.** true
c5f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  ..**.** The impl
c600: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
c610: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 20  ese routines in 
c620: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a  the SQLite core.
c630: 2a 2a 20 69 73 20 6f 6d 69 74 74 65 64 20 69 66  ** is omitted if
c640: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c650: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
c660: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
c670: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
c680: 43 41 54 49 4f 4e 20 6d 61 63 72 6f 20 64 65 66  CATION macro def
c690: 69 6e 65 64 2e 20 20 49 6e 20 74 68 61 74 20 63  ined.  In that c
c6a0: 61 73 65 2c 0a 2a 2a 20 74 68 65 20 61 70 70 6c  ase,.** the appl
c6b0: 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e  ication that lin
c6c0: 6b 73 20 53 51 4c 69 74 65 20 6d 75 73 74 20 70  ks SQLite must p
c6d0: 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 0a 2a  rovide its own.*
c6e0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  * alternative im
c6f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53  plementation.  S
c700: 65 65 20 74 68 65 20 64 6f 63 75 6d 65 6e 74 61  ee the documenta
c710: 74 69 6f 6e 20 6f 6e 0a 2a 2a 20 5b 73 71 6c 69  tion on.** [sqli
c720: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
c730: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
c740: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  ormation..*/.sql
c750: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
c760: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
c770: 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
c780: 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
c790: 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
c7a0: 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
c7b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
c7c0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
c7d0: 41 6c 61 72 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Alarms.**.** The
c7e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c7f0: 5f 61 6c 61 72 6d 5d 20 72 6f 75 74 69 6e 65 20  _alarm] routine 
c800: 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  is used to regis
c810: 74 65 72 0a 2a 2a 20 61 20 63 61 6c 6c 62 61 63  ter.** a callbac
c820: 6b 20 6f 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  k on memory allo
c830: 63 61 74 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a  cation events..*
c840: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
c850: 65 20 72 65 67 69 73 74 65 72 73 20 6f 72 20 63  e registers or c
c860: 6c 65 61 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  lears a callback
c870: 73 20 74 68 61 74 20 66 69 72 65 73 20 77 68 65  s that fires whe
c880: 6e 0a 2a 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20  n.** the amount 
c890: 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
c8a0: 74 65 64 20 65 78 63 65 65 64 73 20 69 54 68 72  ted exceeds iThr
c8b0: 65 73 68 6f 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a  eshold.  Only.**
c8c0: 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
c8d0: 63 6b 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ck can be regist
c8e0: 65 72 65 64 20 61 74 20 61 20 74 69 6d 65 2e 20  ered at a time. 
c8f0: 20 45 61 63 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f   Each call.** to
c900: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c910: 5f 61 6c 61 72 6d 28 29 5d 20 6f 76 65 72 77 72  _alarm()] overwr
c920: 69 74 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ites the previou
c930: 73 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  s callback..** T
c940: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 64  he callback is d
c950: 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
c960: 6e 67 20 78 43 61 6c 6c 62 61 63 6b 20 74 6f 20  ng xCallback to 
c970: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
c980: 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 70 61  r..** .** The pa
c990: 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
c9a0: 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 74 68 65  callback are the
c9b0: 20 70 41 72 67 20 76 61 6c 75 65 2c 20 74 68 65   pArg value, the
c9c0: 20 0a 2a 2a 20 61 6d 6f 75 6e 74 20 6f 66 20 6d   .** amount of m
c9d0: 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
c9e0: 69 6e 20 75 73 65 2c 20 61 6e 64 20 74 68 65 20  in use, and the 
c9f0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61  size of the.** a
ca00: 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 70  llocation that p
ca10: 72 6f 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  rovoked the call
ca20: 62 61 63 6b 2e 20 20 54 68 65 20 63 61 6c 6c 62  back.  The callb
ca30: 61 63 6b 20 77 69 6c 6c 0a 2a 2a 20 70 72 65 73  ack will.** pres
ca40: 75 6d 61 62 6c 79 20 69 6e 76 6f 6b 65 20 5b 73  umably invoke [s
ca50: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74  qlite3_free()] t
ca60: 6f 20 66 72 65 65 20 75 70 20 6d 65 6d 6f 72 79  o free up memory
ca70: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 63   space..** The c
ca80: 61 6c 6c 62 61 63 6b 20 6d 61 79 20 69 6e 76 6f  allback may invo
ca90: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ke [sqlite3_mall
caa0: 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
cab0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
cac0: 62 75 74 20 69 66 20 69 74 20 64 6f 65 73 2c 20  but if it does, 
cad0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  no additional ca
cae0: 6c 6c 62 61 63 6b 73 20 77 69 6c 6c 20 62 65 20  llbacks will be 
caf0: 69 6e 76 6f 6b 65 64 20 62 79 0a 2a 2a 20 74 68  invoked by.** th
cb00: 65 20 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c  e recursive call
cb10: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  s..**.** The [sq
cb20: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
cb30: 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
cb40: 63 65 20 77 6f 72 6b 73 20 62 79 20 72 65 67 69  ce works by regi
cb50: 73 74 65 72 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d  stering.** a mem
cb60: 6f 72 79 20 61 6c 61 72 6d 20 61 74 20 74 68 65  ory alarm at the
cb70: 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
cb80: 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a   and invoking .*
cb90: 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
cba0: 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 20  se_memory()] in 
cbb0: 74 68 65 20 61 6c 61 72 6d 20 63 61 6c 6c 62 61  the alarm callba
cbc0: 63 6b 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ck.  Application
cbd0: 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 20 73 68 6f  .** programs sho
cbe0: 75 6c 64 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  uld not attempt 
cbf0: 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
cc00: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
cc10: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
cc20: 20 62 65 63 61 75 73 65 20 64 6f 69 6e 67 20 73   because doing s
cc30: 6f 20 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65  o will interfere
cc40: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
cc50: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
cc60: 6c 69 6d 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e  limit()] module.
cc70: 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
cc80: 20 69 73 20 65 78 70 6f 73 65 64 0a 2a 2a 20 6f   is exposed.** o
cc90: 6e 6c 79 20 73 6f 20 74 68 61 74 20 61 70 70 6c  nly so that appl
cca0: 69 63 61 74 69 6f 6e 73 20 63 61 6e 20 70 72 6f  ications can pro
ccb0: 76 69 64 65 20 74 68 65 69 72 20 6f 77 6e 0a 2a  vide their own.*
ccc0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  * alternative im
ccd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
cce0: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
ccf0: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
cd00: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49   with SQLITE_OMI
cd10: 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
cd20: 49 4f 4e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ION..*/.int sqli
cd30: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
cd40: 28 0a 20 20 76 6f 69 64 28 2a 78 43 61 6c 6c 62  (.  void(*xCallb
cd50: 61 63 6b 29 28 76 6f 69 64 20 2a 70 41 72 67 2c  ack)(void *pArg,
cd60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 75   sqlite3_int64 u
cd70: 73 65 64 2c 20 69 6e 74 20 4e 29 2c 0a 20 20 76  sed, int N),.  v
cd80: 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c  oid *pArg,.  sql
cd90: 69 74 65 33 5f 69 6e 74 36 34 20 69 54 68 72 65  ite3_int64 iThre
cda0: 73 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  shold.);.../*.**
cdb0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
cdc0: 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
cdd0: 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
cde0: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ***.** This rout
cdf0: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
ce00: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
ce10: 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c  ack with the SQL
ce20: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a  ite library.  .*
ce30: 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
ce40: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
ce50: 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
ce60: 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
ce70: 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
ce80: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
ce90: 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
cea0: 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
ceb0: 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
cec0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
ced0: 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
cee0: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
cef0: 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
cf00: 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
cf10: 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
cf20: 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
cf30: 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
cf40: 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
cf50: 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
cf60: 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
cf70: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
cf80: 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
cf90: 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
cfa0: 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
cfb0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
cfc0: 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
cfd0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
cfe0: 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
cff0: 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
d000: 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
d010: 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
d020: 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
d030: 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
d040: 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
d050: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
d060: 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
d070: 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
d080: 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
d090: 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
d0a0: 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
d0b0: 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20   error.  .**.** 
d0c0: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  Depending on the
d0d0: 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51   action, the [SQ
d0e0: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64  LITE_IGNORE] and
d0f0: 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72   [SQLITE_DENY] r
d100: 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d  eturn.** codes m
d110: 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68  ight mean someth
d120: 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72  ing different or
d130: 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e   they might mean
d140: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69   the same.** thi
d150: 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69  ng.  If the acti
d160: 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70  on is, for examp
d170: 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61  le, to perform a
d180: 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e   delete opertion
d190: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54  ,.** then [SQLIT
d1a0: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
d1b0: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68  QLITE_DENY] both
d1c0: 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65   cause the state
d1d0: 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  ment compilation
d1e0: 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68  .** to fail with
d1f0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20   an error.  But 
d200: 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  if the action is
d210: 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69   to read a speci
d220: 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72  fic column.** fr
d230: 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61  om a specific ta
d240: 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ble, then [SQLIT
d250: 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75  E_DENY] will cau
d260: 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a  se the entire.**
d270: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61   statement to fa
d280: 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49  il but [SQLITE_I
d290: 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73  GNORE] will caus
d2a0: 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74  e a NULL value t
d2b0: 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73  o be.** read ins
d2c0: 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75  tead of the actu
d2d0: 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  al column value.
d2e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
d2f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
d300: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
d310: 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
d320: 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  of.** the third 
d330: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
d340: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
d350: 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
d360: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ace..** The seco
d370: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
d380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
d390: 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b  an integer .** [
d3a0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
d3b0: 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
d3c0: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
d3d0: 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
d3e0: 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  ** to be authori
d3f0: 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61  zed.  The availa
d400: 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ble action codes
d410: 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   are.** [SQLITE_
d420: 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65  COPY | documente
d430: 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20  d separately].  
d440: 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
d450: 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
d460: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
d470: 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67  lback are string
d480: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
d490: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
d4a0: 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
d4b0: 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
d4c0: 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
d4d0: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
d4e0: 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69  sed when prepari
d4f0: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
d500: 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
d510: 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74  ted.** source, t
d520: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
d530: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
d540: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
d550: 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68  ccess data.** th
d560: 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  at they are not 
d570: 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
d580: 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
d590: 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78  not try to.** ex
d5a0: 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
d5b0: 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
d5c0: 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
d5d0: 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
d5e0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
d5f0: 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
d600: 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
d610: 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
d620: 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
d630: 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
d640: 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
d650: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
d660: 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
d670: 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
d680: 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
d690: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
d6a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
d6b0: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
d6c0: 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
d6d0: 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
d6e0: 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
d6f0: 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70  d SQL is being p
d700: 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73  repared that dis
d710: 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
d720: 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45  g.** except SELE
d730: 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  CT statements.  
d740: 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
d750: 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
d760: 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
d770: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
d780: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
d790: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
d7a0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
d7b0: 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
d7c0: 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
d7d0: 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e  vious call.  A N
d7e0: 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
d7f0: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
d800: 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
d810: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
d820: 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
d830: 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55  authorizer is NU
d840: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  LL..**.** Note t
d850: 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
d860: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
d870: 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
d880: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
d890: 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
d8a0: 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
d8b0: 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
d8c0: 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
d8d0: 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
d8e0: 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
d8f0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
d900: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
d910: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
d920: 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
d930: 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
d940: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
d950: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
d960: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
d970: 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
d980: 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
d990: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
d9a0: 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
d9b0: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
d9c0: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
d9d0: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
d9e0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
d9f0: 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
da00: 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
da10: 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
da20: 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
da30: 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
da40: 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
da50: 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
da60: 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
da70: 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
da80: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
da90: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
daa0: 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
dab0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
dac0: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
dad0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
dae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
daf0: 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
db00: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
db10: 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
db20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
db30: 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
db40: 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
db50: 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
db60: 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
db70: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
db80: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
db90: 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
dba0: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
dbb0: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
dbc0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
dbd0: 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
dbe0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
dbf0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
dc00: 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69  uthorizer certai
dc10: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
dc20: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
dc30: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
dc40: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
dc50: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
dc60: 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
dc70: 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
dc80: 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
dc90: 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
dca0: 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
dcb0: 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
dcc0: 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
dcd0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
dce0: 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
dcf0: 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
dd00: 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
dd10: 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
dd20: 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
dd30: 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  e .** authorized
dd40: 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
dd50: 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
dd60: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
dd70: 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  on callback.** f
dd80: 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
dd90: 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
dda0: 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
ddb0: 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
ddc0: 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
ddd0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
dde0: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
ddf0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
de00: 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
de10: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
de20: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
de30: 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
de40: 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29  temp", .** etc.)
de50: 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
de60: 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
de70: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
de80: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
de90: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
dea0: 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
deb0: 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
dec0: 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
ded0: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
dee0: 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
def0: 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
df00: 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
df10: 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
df20: 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
df30: 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
df40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
df50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
df60: 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
df70: 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
df80: 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
df90: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
dfa0: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
dfb0: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
dfc0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
dfd0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
dfe0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
dff0: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
e000: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e010: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e020: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e030: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
e040: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
e050: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
e060: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
e070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e080: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
e090: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
e0a0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e0b0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
e0c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e0d0: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
e0e0: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
e0f0: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
e100: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
e110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e120: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
e130: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
e140: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
e150: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e170: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
e180: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
e190: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
e1a0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
e1b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e1c0: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
e1d0: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
e1e0: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
e1f0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
e210: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
e220: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
e230: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
e240: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
e260: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
e270: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
e280: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
e290: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
e2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
e2b0: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
e2c0: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
e2d0: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
e2e0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e2f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
e300: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
e310: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
e320: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
e330: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
e340: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
e350: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
e360: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
e370: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
e380: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
e390: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
e3a0: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
e3b0: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
e3c0: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
e3d0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
e3e0: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
e3f0: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
e400: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
e410: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
e420: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e430: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
e440: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
e450: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
e460: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
e470: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
e480: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
e490: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
e4a0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
e4b0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
e4c0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
e4d0: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
e4e0: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
e4f0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
e500: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
e510: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
e520: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
e530: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
e540: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
e550: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
e560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e570: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
e580: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
e590: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
e5a0: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
e5b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e5c0: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
e5d0: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
e5e0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
e5f0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
e600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e610: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
e620: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
e630: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
e640: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
e650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e660: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
e670: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
e680: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
e690: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
e6a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e6b0: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
e6c0: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
e6d0: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
e6e0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
e700: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
e710: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
e720: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
e730: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
e750: 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
e760: 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
e770: 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
e780: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
e790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
e7a0: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
e7b0: 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
e7c0: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
e7d0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e7e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
e7f0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
e800: 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
e810: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
e820: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e830: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
e840: 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
e850: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
e860: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
e870: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
e880: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
e890: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
e8a0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
e8b0: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
e8c0: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
e8d0: 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
e8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
e8f0: 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
e900: 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
e910: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e920: 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
e930: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
e940: 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
e950: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e960: 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
e970: 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
e980: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
e990: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
e9a0: 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
e9b0: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
e9c0: 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
e9d0: 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
e9e0: 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
e9f0: 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
ea00: 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61  ments..** The ca
ea10: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
ea20: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
ea30: 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
ea40: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74   invoked.** at t
ea50: 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65  he first [sqlite
ea60: 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68  3_step()] for th
ea70: 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
ea80: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
ea90: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
eaa0: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
eab0: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
eac0: 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
ead0: 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
eae0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
eaf0: 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c  inishes and incl
eb00: 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  udes.** informat
eb10: 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20  ion on how long 
eb20: 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72  that statement r
eb30: 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  an..**.** The sq
eb40: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
eb50: 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79  API is currently
eb60: 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
eb70: 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20  rimental and.** 
eb80: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
eb90: 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ange..*/.void *s
eba0: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
ebb0: 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
ebc0: 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
ebd0: 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
ebe0: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
ebf0: 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
ec00: 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
ec10: 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
ec20: 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
ec30: 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
ec40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ec50: 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
ec60: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
ec70: 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
ec80: 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
ec90: 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
eca0: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
ecb0: 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ck - that.** is 
ecc0: 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
ecd0: 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
ece0: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
ecf0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
ed00: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
ed10: 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
ed20: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
ed30: 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
ed40: 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
ed50: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
ed60: 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
ed70: 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
ed80: 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  e query..**.** T
ed90: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
eda0: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
edb0: 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
edc0: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
edd0: 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65   opcodes,.** whe
ede0: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
edf0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
ee00: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
ee10: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
ee20: 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73  ack.** itself is
ee30: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
ee40: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
ee50: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
ee60: 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  on. The fourth.*
ee70: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
ee80: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
ee90: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
eea0: 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
eeb0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
eec0: 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
eed0: 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
eee0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
eef0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ll to [sqlite3_e
ef00: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
ef10: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71  _step()], or [sq
ef20: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
ef30: 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  )].** results in
ef40: 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
ef50: 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
ef60: 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
ef70: 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c  rogress .** call
ef80: 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
ef90: 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e  voked..** .** On
efa0: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
efb0: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75  ress callback fu
efc0: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
efd0: 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63  gistered for eac
efe0: 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  h.** open databa
eff0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
f000: 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71  Every call to sq
f010: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
f020: 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72  andler().** over
f030: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
f040: 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  ts of the previo
f050: 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72  us call..** To r
f060: 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65  emove the progre
f070: 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f  ss callback alto
f080: 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c  gether, pass NUL
f090: 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  L as the third.*
f0a0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
f0b0: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
f0c0: 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
f0d0: 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
f0e0: 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
f0f0: 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20  er than 0, then 
f100: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
f110: 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61  query is immedia
f120: 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20  tely terminated 
f130: 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65  and any database
f140: 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20   changes rolled 
f150: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e  back..** The con
f160: 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33  taining [sqlite3
f170: 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
f180: 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a  e3_step()], or.*
f190: 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
f1a0: 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74  able()] call ret
f1b0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45  urns SQLITE_INTE
f1c0: 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65  RRUPT.   This fe
f1d0: 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20  ature.** can be 
f1e0: 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
f1f0: 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  e, to implement 
f200: 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74  the "Cancel" but
f210: 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67  ton on a.** prog
f220: 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20  ress dialog box 
f230: 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69  in a GUI..*/.voi
f240: 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
f250: 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
f260: 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
f270: 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
f280: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f290: 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
f2a0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
f2b0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74  ion.**.** Open t
f2c0: 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61  he sqlite databa
f2d0: 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d  se file "filenam
f2e0: 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61  e".  The "filena
f2f0: 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20  me" is UTF-8.** 
f300: 65 6e 63 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c  encoded for [sql
f310: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
f320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
f330: 32 28 29 5d 20 61 6e 64 20 55 54 46 2d 31 36 20  2()] and UTF-16 
f340: 65 6e 63 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68  encoded.** in th
f350: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
f360: 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
f370: 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41  _open16()]..** A
f380: 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  n [sqlite3*] han
f390: 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  dle is returned 
f3a0: 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
f3b0: 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
f3c0: 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74  curs. If the dat
f3d0: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
f3e0: 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  (or created) suc
f3f0: 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68  cessfully,.** th
f400: 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
f410: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
f420: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
f430: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
f440: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
f450: 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
f460: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
f470: 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  )]  routines can
f480: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
f490: 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
f4a0: 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
f4b0: 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
f4c0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
f4d0: 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
f4e0: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
f4f0: 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
f500: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
f510: 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
f520: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63  _open_v2()] is c
f530: 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
f540: 2d 31 36 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  -16 if [sqlite3_
f550: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
f560: 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
f570: 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
f580: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
f590: 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
f5a0: 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a  rces associated.
f5b0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
f5c0: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
f5d0: 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
f5e0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
f5f0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c  o.** [sqlite3_cl
f600: 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
f610: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
f620: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
f630: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
f640: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
f650: 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
f660: 33 5f 6f 70 65 6e 28 29 5d 20 65 78 63 65 70 74  3_open()] except
f670: 20 74 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65   that.** provide
f680: 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
f690: 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
f6a0: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
f6b0: 6f 6c 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e  ol over the.** n
f6c0: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
f6d0: 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
f6e0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
f6f0: 20 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a   be one of:.**.*
f700: 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ol>.** <li>  
f710: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
f720: 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  DONLY].** <li>  
f730: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
f740: 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  DWRITE].** <li> 
f750: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
f760: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
f770: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a  TE_OPEN_CREATE].
f780: 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ol>.**.** T
f790: 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f  he first value o
f7a0: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
f7b0: 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66  e read-only.  If
f7c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
f7d0: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f  es.** not previo
f7e0: 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
f7f0: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
f800: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70  .  The second op
f810: 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68  tion opens.** th
f820: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
f830: 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
f840: 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
f850: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
f860: 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  if.** if the fil
f870: 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
f880: 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72  cted.  In either
f890: 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
f8a0: 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a  se must already.
f8b0: 2a 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65  ** exist or an e
f8c0: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
f8d0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74  .  The third opt
f8e0: 69 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61  ion opens the da
f8f0: 74 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65  tabase.** for re
f900: 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
f910: 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74  g and creates it
f920: 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
f930: 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a  already exist..*
f940: 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  * The third opti
f950: 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20  ons is behavior 
f960: 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
f970: 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  sed for [sqlite3
f980: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
f990: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
f9a0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
f9b0: 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
f9c0: 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
f9d0: 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d   private.** in-m
f9e0: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
f9f0: 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
fa00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
fa10: 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  his in-memory.**
fa20: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
fa30: 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64  anish when the d
fa40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fa50: 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
fa60: 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
fa70: 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
fa80: 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
fa90: 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
faa0: 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61  filenames.** tha
fab0: 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
fac0: 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20   ":" character. 
fad0: 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
fae0: 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e  ed that .** when
faf0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
fb00: 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73  name really does
fb10: 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22   begin with.** "
fb20: 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66  :" that you pref
fb30: 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
fb40: 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
fb50: 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20  like "./" to.** 
fb60: 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
fb70: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
fb80: 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
fb90: 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
fba0: 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72  a private tempor
fbb0: 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
fbc0: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
fbd0: 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
fbe0: 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
fbf0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
fc00: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
fc10: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
fc20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fc30: 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
fc40: 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
fc50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
fc60: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
fc70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
fc80: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
fc90: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
fca0: 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
fcb0: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20  ting system .** 
fcc0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
fcd0: 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
fce0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
fcf0: 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a  d use.  If the.*
fd00: 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
fd10: 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  er is a NULL poi
fd20: 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
fd30: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
fd40: 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  fs].** object is
fd50: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
fd60: 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20  Note to windows 
fd70: 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
fd80: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
fd90: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
fda0: 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73  rgument.** of [s
fdb0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
fdc0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
fdd0: 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55  _v2()] must be U
fde0: 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
fdf0: 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
fe00: 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
fe10: 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
fe20: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
fe30: 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
fe40: 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
fe50: 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
fe60: 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
fe70: 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
fe80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
fe90: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
fea0: 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
feb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
fec0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
fed0: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
fee0: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
fef0: 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
ff00: 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
ff10: 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
ff20: 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
ff30: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
ff40: 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
ff50: 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
ff60: 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
ff70: 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
ff80: 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
ff90: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
ffa0: 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
ffb0: 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
ffc0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
ffd0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
ffe0: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
fff0: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
10000 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
10010 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
10020 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
10030 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
10040 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
10050 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
10060 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
10070 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
10080 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
10090 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
100a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
100b0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
100c0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
100d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
100e0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
100f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
10100 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eric.** [SQLITE_
10110 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
10120 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
10130 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
10140 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a  ed result code].
10150 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  ** for the most 
10160 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
10170 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
10180 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
10190 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61  ith [sqlite3] ha
101a0 6e 64 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61  ndle 'db'.  If a
101b0 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
101c0 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a  failed but the.*
101d0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  * most recent AP
101e0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
101f0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
10200 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
10210 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20  errcode().** is 
10220 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a  undefined. .**.*
10230 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
10240 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
10250 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
10260 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
10270 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
10280 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
10290 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
102a0 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  r UTF8 or UTF16 
102b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
102c0 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
102d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
102e0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
102f0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20  ged internally. 
10300 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20   The .** string 
10310 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74  may be overwritt
10320 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
10330 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20  d by subsequent 
10340 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a  calls to SQLite.
10350 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  ** interface fun
10360 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61  ctions..**.** Ca
10370 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69  lls to many sqli
10380 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20  te3_* functions 
10390 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f  set the error co
103a0 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65  de and string re
103b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
103c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
103d0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
103e0 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
103f0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
10400 2a 20 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74  * (overwriting t
10410 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75  he previous valu
10420 65 73 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63  es). Note that c
10430 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
10440 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
10450 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
10460 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
10470 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65  _errmsg16()] the
10480 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
10490 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73  ffect the.** res
104a0 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69  ults of future i
104b0 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c  nvocations.  Cal
104c0 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
104d0 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
104e0 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f  eturn.** an erro
104f0 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
10500 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
10510 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
10520 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 65 72  ** change the er
10530 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65  ror code returne
10540 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
10550 65 2e 20 20 49 6e 74 65 72 66 61 63 65 73 20 74  e.  Interfaces t
10560 68 61 74 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 61  hat are.** not a
10570 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
10580 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
10590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65  se connection (e
105a0 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c  xamples:.** [sql
105b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
105c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  or [sqlite3_enab
105d0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
105e0 29 5d 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65  )] do not change
105f0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 63  .** the return c
10600 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73  ode.  .**.** Ass
10610 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69  uming no other i
10620 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c 69 74  ntervening sqlit
10630 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 20 61  e3_* API calls a
10640 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65 72 72  re made, the err
10650 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74 75 72  or.** code retur
10660 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
10670 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74  tion is associat
10680 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
10690 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65   error as.** the
106a0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
106b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
106c0 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
106d0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
106e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
106f0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
10700 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
10710 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
10720 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
10730 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
10740 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
10750 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10760 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
10770 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
10780 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   Instance of thi
10790 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
107a0 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74  nt single SQL st
107b0 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a  atements.  This.
107c0 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ** is variously 
107d0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
107e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
107f0 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c  or a .** "compil
10800 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
10810 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
10820 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
10830 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66   .** The life of
10840 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
10850 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
10860 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
10870 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
10880 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
10890 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
108a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
108b0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
108c0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
108d0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
108e0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
108f0 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20  eters using.**  
10900 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
10910 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
10920 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63  _bind_* interfac
10930 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  es]..** <li> Run
10940 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
10950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
10960 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
10970 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
10980 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
10990 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
109a0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
109b0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
109c0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
109d0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
109e0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
109f0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
10a00 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
10a10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
10a20 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
10a30 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
10a40 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
10a50 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
10a60 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
10a70 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
10a80 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10a90 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
10aa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
10ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10ac0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
10ad0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
10ae0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
10af0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
10b00 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
10b10 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
10b20 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
10b30 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
10b40 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
10b50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10b60 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
10b70 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69   [sqlite3 | SQLi
10b80 74 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  te database hand
10b90 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  le] .** obtained
10ba0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61   from a prior ca
10bb0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
10bc0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
10bd0 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f  _open_v2()].** o
10be0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
10bf0 36 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63  6()]..** The sec
10c00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53  ond argument "zS
10c10 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65  ql" is the state
10c20 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
10c30 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
10c40 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
10c50 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
10c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
10c70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
10c80 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
10c90 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54  terfaces uses UT
10ca0 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  F-8 and sqlite3_
10cb0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
10cc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
10cd0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
10ce0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  F-16..**.** If t
10cf0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
10d00 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
10d10 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
10d20 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
10d30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
10d40 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a  erminator.  If.*
10d50 2a 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  * nByte is non-n
10d60 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
10d70 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
10d80 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79  number of .** by
10d90 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
10da0 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
10db0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
10dc0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
10dd0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
10de0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
10df0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
10e00 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e   .** until the n
10e10 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
10e20 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
10e30 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  rst..**.** *pzTa
10e40 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
10e50 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
10e60 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
10e70 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a  nd of the first.
10e80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
10e90 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20   in zSql.  This 
10ea0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d  routine only com
10eb0 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 20  piles the first 
10ec0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20  statement.** in 
10ed0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
10ee0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
10ef0 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
10f00 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
10f10 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
10f20 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
10f30 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b  a compiled .** [
10f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
10f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72  QL statement str
10f60 75 63 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e  ucture] that can
10f70 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
10f80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
10f90 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74  tep()].  Or if t
10fa0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
10fb0 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65  , *ppStmt may be
10fc0 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e  .** set to NULL.
10fd0 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
10fe0 65 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f  ext contained no
10ff0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
11000 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70  ut is and.** emp
11010 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
11020 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
11030 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
11040 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ULL.  The callin
11050 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72 65 20 69  g.** procedure i
11060 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11070 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
11080 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
11090 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
110a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
110b0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
110c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
110d0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
110e0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
110f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
11100 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20  therwise an .** 
11110 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
11120 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
11130 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
11140 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
11150 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
11160 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
11170 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
11180 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
11190 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
111a0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
111b0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
111c0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
111d0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
111e0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
111f0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
11200 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
11210 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
11220 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
11230 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
11240 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
11250 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
11260 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
11270 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
11280 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c  the .** original
11290 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
112a0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
112b0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
112c0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
112d0 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
112e0 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
112f0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
11300 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
11310 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
11320 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
11330 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
11340 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
11350 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
11360 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
11370 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
11380 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
11390 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
113a0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
113b0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
113c0 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
113d0 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 20 61  has changed in a
113e0 20 77 61 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b   way.** that mak
113f0 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
11400 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
11410 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
11420 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
11430 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11440 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
11450 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
11460 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
11470 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
11480 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
11490 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
114a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
114b0 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
114c0 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
114d0 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
114e0 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
114f0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
11500 6e 64 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  nd the text of t
11510 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72  he parsing.** er
11520 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
11530 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
11540 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
11550 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
11560 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
11570 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20  ror occurs, .** 
11580 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11590 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
115a0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
115b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
115c0 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
115d0 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  s] or.** [SQLITE
115e0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
115f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
11600 64 65 73 5d 20 73 75 63 68 20 61 73 20 64 69 72  des] such as dir
11610 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65  ectly..** The le
11620 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
11630 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
11640 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
11650 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
11660 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ric.** [SQLITE_E
11670 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
11680 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  e and you would 
11690 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
116a0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a  econd call to.**
116b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
116c0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
116d0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
116e0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
116f0 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68  problem..** With
11700 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
11710 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  e interfaces, th
11720 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
11730 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
11740 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  r is.** returned
11750 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
11760 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
11770 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
11780 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
11790 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
117a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
117b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
117c0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
117d0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
117e0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
117f0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
11800 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
11810 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
11820 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
11830 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
11840 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
11850 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
11860 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
11870 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
11880 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
11890 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
118a0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
118b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
118c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
118d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
118e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
118f0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
11900 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
11910 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
11920 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
11930 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
11940 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
11950 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
11960 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
11970 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
11980 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
11990 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
119a0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
119b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
119c0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
119d0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
119e0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
119f0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
11a00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
11a10 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
11a20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11a30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
11a40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
11a50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
11a60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
11a70 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
11a80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
11a90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
11aa0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
11ab0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
11ac0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
11ad0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
11ae0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
11af0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
11b00 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
11b10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
11b20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
11b30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
11b40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
11b50 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
11b60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
11b70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
11b80 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
11b90 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
11ba0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
11bb0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
11bc0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
11bd0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
11be0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
11bf0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
11c00 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
11c10 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
11c20 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
11c30 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
11c40 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
11c50 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
11c60 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
11c70 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
11c80 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
11c90 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e  * CAPI3REF:  Dyn
11ca0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
11cb0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  alue Object.**.*
11cc0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
11cd0 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72  namic typing for
11ce0 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
11cf0 74 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63  tores.  Values c
11d00 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65  an .** be intege
11d10 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
11d20 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
11d30 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
11d40 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73  LL.  When.** pas
11d50 73 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75  sing around valu
11d60 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65  es internally, e
11d70 61 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70  ach value is rep
11d80 72 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61  resented as.** a
11d90 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11da0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
11db0 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
11dc0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
11dd0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
11de0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
11df0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
11e00 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
11e10 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
11e20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
11e30 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
11e40 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
11e50 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
11e60 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
11e70 6e 74 65 72 20 74 6f 20 73 75 63 68 20 61 6e 20  nter to such an 
11e80 6f 62 6a 65 63 74 20 69 73 20 74 68 65 0a 2a 2a  object is the.**
11e90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11ea0 20 74 6f 20 75 73 65 72 2d 64 65 66 69 6e 65 64   to user-defined
11eb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a   SQL functions..
11ec0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11ed0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
11ee0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
11ef0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
11f00 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c  EF:  Binding Val
11f10 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
11f20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a  Statements.**.**
11f30 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
11f40 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
11f50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11f60 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
11f70 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ants,.** one or 
11f80 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73 20 63 61  more literals ca
11f90 6e 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20  n be replace by 
11fa0 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
11fb0 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66  ne of these.** f
11fc0 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
11fd0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
11fe0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
11ff0 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20  >  :AAA.** <li> 
12000 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @AAA.** <li>  $
12010 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
12020 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
12030 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
12040 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
12050 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
12060 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e 20 61 6c  .** AAA is an al
12070 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
12080 69 66 69 65 72 20 61 6e 64 20 56 56 56 20 69 73  ifier and VVV is
12090 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65   a variable name
120a0 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
120b0 20 74 68 65 20 73 79 6e 74 61 78 20 72 75 6c 65   the syntax rule
120c0 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70 72 6f  s of the TCL pro
120d0 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67  gramming languag
120e0 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  e..** The values
120f0 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
12100 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
12110 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
12120 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e  r names").** can
12130 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
12140 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
12150 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
12160 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
12170 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12180 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
12190 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
121a0 6e 65 73 20 61 6c 77 61 79 73 20 69 73 20 61 20  nes always is a 
121b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
121c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
121d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
121e0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
121f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
12200 2a 2a 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  ** its variants.
12210 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20    The second.** 
12220 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
12230 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72  index of the par
12240 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
12250 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
12260 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e  ameter has.** an
12270 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 57 68 65   index of 1. Whe
12280 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
12290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
122a0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
122b0 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64  e, second.** and
122c0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
122d0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
122e0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
122f0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
12300 72 72 65 6e 63 65 2e 20 20 54 68 65 20 69 6e 64  rrence.  The ind
12310 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20  ex for.** named 
12320 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
12330 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
12340 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
12350 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
12360 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20  _name()] API if 
12370 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
12380 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a  dex for "?NNN".*
12390 2a 20 70 61 72 61 6d 65 74 65 73 20 69 73 20 74  * parametes is t
123a0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
123b0 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
123c0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
123d0 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
123e0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
123f0 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
12400 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
12410 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
12420 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61   999)..** See <a
12430 20 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74   href="limits.ht
12440 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c  ml">limits.html<
12450 2f 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  /a> for addition
12460 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
12470 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
12480 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
12490 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
124a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
124b0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a  **.** In those.*
124c0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
124d0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
124e0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
124f0 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
12500 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74  of bytes.** in t
12510 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
12520 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
12530 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
12540 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
12550 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e  the.** string, n
12560 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
12570 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 54 68   characters.  Th
12580 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
12590 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ytes does not in
125a0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74  clude the zero-t
125b0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
125c0 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e   end of strings.
125d0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
125e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
125f0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
12600 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
12610 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  g is.** number o
12620 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
12630 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
12640 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
12650 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
12660 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
12670 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
12680 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
12690 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
126a0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
126b0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
126c0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
126d0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65  he BLOB or.** te
126e0 78 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  xt after SQLite 
126f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
12700 68 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69  h it.  If the fi
12710 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20  fth argument is 
12720 74 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76  the.** special v
12730 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
12740 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c  TIC], then the l
12750 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74  ibrary assumes t
12760 68 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74  hat the informat
12770 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61  ion.** is in sta
12780 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
12790 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
127a0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
127b0 65 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  ed.  If the.** f
127c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
127d0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
127e0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
127f0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
12800 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69  s its.** own pri
12810 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
12820 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
12830 79 2c 20 62 65 66 6f 72 65 20 74 68 65 20 73 71  y, before the sq
12840 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
12850 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
12860 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
12870 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
12880 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
12890 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
128a0 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73  gth n that.** is
128b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
128c0 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  os.  A zeroblob 
128d0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
128e0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
128f0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
12900 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a  r to hold it siz
12910 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
12920 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
12930 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
12940 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
12950 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64  ve as place-hold
12960 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
12970 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
12980 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
12990 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
129a0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
129b0 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f  ncrement BLOB I/
129c0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 20  O] routines.  A 
129d0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75  negative.** valu
129e0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
129f0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
12a00 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
12a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12a20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
12a30 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
12a40 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
12a50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
12a60 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
12a70 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
12a80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
12a90 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
12aa0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
12ab0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
12ac0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
12ad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
12ae0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
12af0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
12b00 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
12b10 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
12b20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
12b30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
12b40 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
12b50 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
12b60 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
12b70 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
12b80 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
12b90 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
12ba0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
12bb0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
12bc0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
12bd0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
12be0 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
12bf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
12c00 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
12c10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
12c20 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69  e called on a vi
12c30 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
12c40 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
12c50 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
12c60 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
12c70 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f  en finalized..*/
12c80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12c90 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
12ca0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
12cb0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
12cc0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
12cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12ce0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
12cf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
12d00 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
12d10 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
12d20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
12d30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
12d40 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
12d50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
12d60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
12d70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12d80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
12d90 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
12da0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
12db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12dc0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
12dd0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
12de0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
12df0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
12e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12e10 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
12e20 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
12e30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
12e40 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
12e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12e60 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
12e70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
12e80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
12e90 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
12ea0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
12eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ec0 20 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20   Number Of Host 
12ed0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
12ee0 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67   Return the larg
12ef0 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  est host paramet
12f00 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20  er index in the 
12f10 70 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74  precompiled stat
12f20 65 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61  ement given.** a
12f30 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20  s the argument. 
12f40 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70   When the host p
12f50 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66  arameters are of
12f60 20 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20   the forms like 
12f70 22 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22  ":AAA".** or "?"
12f80 2c 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20  , then they are 
12f90 61 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74  assigned sequent
12fa0 69 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e  ial increasing n
12fb0 75 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67  umbers beginning
12fc0 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f  .** with one, so
12fd0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12fe0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
12ff0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e  r of parameters.
13000 20 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20    However.** if 
13010 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61  the same host pa
13020 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20  rameter name is 
13030 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  used multiple ti
13040 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72  mes, each occurr
13050 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  ance.** is given
13060 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
13070 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
13080 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20  eturned in that 
13090 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62  case is the numb
130a0 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20  er.** of unique 
130b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
130c0 61 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70  ames.  If host p
130d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
130e0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20   form "?NNN".** 
130f0 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20  are used (where 
13100 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
13110 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69  r) then there mi
13120 67 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74  ght be gaps in t
13130 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20  he.** numbering 
13140 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65  and the value re
13150 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69  turned by this i
13160 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
13170 69 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20  index of the.** 
13180 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
13190 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20  ith the largest 
131a0 69 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a  index value..**.
131b0 2a 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20  ** The prepared 
131c0 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e  statement must n
131d0 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66  ot be [sqlite3_f
131e0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
131f0 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  zed].** prior to
13200 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
13210 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72  turnning.  Other
13220 77 69 73 65 20 74 68 65 20 72 65 73 75 6c 74 73  wise the results
13230 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
13240 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  * and probably u
13250 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69  ndesirable..*/.i
13260 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
13270 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
13280 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
13290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
132a0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
132b0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
132c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
132d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
132e0 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
132f0 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
13300 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   in a .** [sqlit
13310 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
13320 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
13330 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * Host parameter
13340 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a  s of the form ":
13350 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
13360 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20  r "$VVV" have a 
13370 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73  name.** which is
13380 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41   the string ":AA
13390 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
133a0 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20  "$VVV".  .** In 
133b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
133c0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
133d0 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73  "$" or "@".** is
133e0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
133f0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
13400 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
13410 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20  the form "?" or 
13420 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e  "?NNN" have no n
13430 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ame..**.** The f
13440 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d  irst bound param
13450 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
13460 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
13470 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
13480 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
13490 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
134a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
134b0 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65  nameless,.** the
134c0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
134d0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
134e0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
134f0 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46  ys in the.** UTF
13500 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
13510 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
13520 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67  rameter was orig
13530 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
13540 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e  .** as UTF-16 in
13550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13560 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  e16()] or [sqlit
13570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13580 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
13590 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
135a0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
135b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
135c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
135d0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
135e0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
135f0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
13600 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
13610 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
13620 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d   of a host param
13630 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69  eter with the gi
13640 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ven name..** The
13650 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68   name must match
13660 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f   exactly.  If no
13670 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
13680 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69  the given name i
13690 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74  s .** found, ret
136a0 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65  urn 0.  Paramete
136b0 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  r names must be 
136c0 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  UTF8..*/.int sql
136d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
136e0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
136f0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
13700 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
13710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
13720 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
13730 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
13740 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43  tatement.**.** C
13750 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
13760 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
13770 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
13780 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
13790 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
137a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
137b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
137c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
137d0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
137e0 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73  ment].  Use this
137f0 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72   routine to.** r
13800 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
13810 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
13820 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13830 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
13840 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
13850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13860 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
13870 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
13880 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  et.**.** Return 
13890 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
138a0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
138b0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
138c0 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   by the .** [sql
138d0 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
138e0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
138f0 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
13900 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
13910 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
13920 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
13930 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
13940 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
13950 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
13960 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
13970 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
13980 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
13990 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
139a0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
139b0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
139c0 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  et.**.** These r
139d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
139e0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
139f0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
13a00 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
13a10 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
13a20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
13a30 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
13a40 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
13a50 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
13a60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13a70 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61   a UTF8 string a
13a80 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
13a90 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65  n_name16().** re
13aa0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
13ab0 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  to a UTF16 strin
13ac0 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
13ad0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
13ae0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
13af0 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
13b00 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65  ment] that imple
13b10 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
13b20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
13b30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13b40 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d  ter is the colum
13b50 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
13b60 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
13b70 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a  is.** number 0..
13b80 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
13b90 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
13ba0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
13bb0 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20   either the .** 
13bc0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13be0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
13bf0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
13c00 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
13c10 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
13c20 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
13c30 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
13c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
13c50 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
13c60 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
13c70 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
13c80 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
13c90 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
13ca0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
13cb0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
13cc0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
13cd0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
13ce0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
13cf0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
13d00 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
13d10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
13d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13d30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
13d40 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
13d50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
13d60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
13d70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
13d80 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
13d90 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
13da0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
13db0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  esult.**.** Thes
13dc0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
13dd0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
13de0 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
13df0 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
13e00 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
13e10 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
13e20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
13e30 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
13e40 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
13e50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
13e60 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
13e70 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
13e80 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
13e90 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
13ea0 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
13eb0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
13ec0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
13ed0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
13ee0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
13ef0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
13f00 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
13f10 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
13f20 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
13f30 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
13f40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
13f50 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
13f60 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  l.** the [sqlite
13f70 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
13f80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
13f90 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
13fa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
13fb0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
13fc0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
13fd0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
13fe0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
13ff0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
14000 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
14010 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
14020 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
14030 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
14040 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
14050 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
14060 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
14070 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14080 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
14090 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20   calls is a .** 
140a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
140b0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
140c0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
140d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
140e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
140f0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
14100 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
14110 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
14120 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
14130 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
14140 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
14150 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  * If the Nth col
14160 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
14170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
14180 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a   an expression.*
14190 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e  * or subquery an
141a0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
141b0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
141c0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
141d0 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e  ions.** return N
141e0 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  ULL. Otherwise, 
141f0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
14200 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
14210 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
14220 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
14230 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
14240 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
14250 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
14260 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
14270 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
14280 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
14290 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
142a0 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d 31 36  6" return UTF-16
142b0 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74 72 69  .** encoded stri
142c0 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
142d0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
142e0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  UTF-8..**.** The
142f0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
14300 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
14310 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
14320 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
14330 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
14340 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
14350 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
14360 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
14370 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
14380 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
14390 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
143a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
143b0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
143c0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
143d0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
143e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
143f0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
14400 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
14410 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
14420 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
14430 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
14440 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
14450 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
14460 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
14470 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
14480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
14490 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
144a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
144b0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
144c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
144d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
144e0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
144f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
14500 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
14510 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
14520 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
14530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
14540 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
14550 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
14560 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
14570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
14580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14590 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
145a0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
145b0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Result.**.** The
145c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
145d0 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   is a [sqlite3_s
145e0 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
145f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  QL statement]. .
14600 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
14610 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
14620 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
14630 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
14640 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
14650 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66  d result set  of
14660 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
14670 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
14680 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
14690 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
146a0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
146b0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
146c0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
146d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
146e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
146f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
14700 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
14710 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
14720 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
14730 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
14740 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
14750 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
14760 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
14770 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d. For example, 
14780 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  in.** the databa
14790 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
147a0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
147b0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
147c0 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c  .** And the foll
147d0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
147e0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
147f0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
14800 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
14810 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   Then this routi
14820 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
14830 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
14840 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
14850 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  ond.** result co
14860 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
14870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
14880 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
14890 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28  sult column.** (
148a0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
148b0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
148c0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
148d0 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
148e0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
148f0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
14900 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
14910 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
14920 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
14930 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
14940 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
14950 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
14960 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
14970 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
14980 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
14990 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
149a0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
149b0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
149c0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
149d0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
149e0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
149f0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
14a00 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
14a10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
14a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
14a30 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
14a40 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f  mt *, int i);.co
14a50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
14a60 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
14a70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
14a80 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20  *,int);../* .** 
14a90 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75  CAPI3REF:  Evalu
14aa0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
14ab0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
14ac0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
14ad0 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
14ae0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
14af0 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
14b00 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
14b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14b20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
14b30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
14b40 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
14b50 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
14b60 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
14b70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
14b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
14b90 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
14ba0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
14bb0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
14bc0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
14bd0 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
14be0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
14bf0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
14c00 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
14c10 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
14c20 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
14c30 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
14c40 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
14c50 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
14c60 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
14c70 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
14c80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14c90 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
14ca0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
14cb0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
14cc0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14cd0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
14ce0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
14cf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
14d00 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
14d10 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
14d20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
14d30 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
14d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
14d50 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
14d60 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
14d70 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
14d80 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
14d90 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
14da0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
14db0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
14dc0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14dd0 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
14de0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
14df0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
14e00 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
14e10 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
14e20 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
14e30 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
14e40 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
14e50 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
14e60 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
14e70 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
14e80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14e90 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
14ea0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
14eb0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
14ec0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
14ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
14ee0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
14ef0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
14f00 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
14f10 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
14f20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
14f30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
14f40 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
14f50 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
14f60 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
14f70 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
14f80 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
14f90 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
14fa0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14fb0 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
14fc0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
14fd0 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
14fe0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
14ff0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
15000 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
15010 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
15020 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
15030 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
15040 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
15050 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
15060 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
15070 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
15080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
15090 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
150a0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
150b0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
150c0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
150d0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
150e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
150f0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
15100 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
15110 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
15120 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
15130 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15140 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
15150 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
15160 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
15170 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
15180 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
15190 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
151a0 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
151b0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
151c0 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
151d0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
151e0 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
151f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
15200 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
15210 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
15220 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
15230 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
15240 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
15250 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
15260 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
15270 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
15280 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
15290 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
152a0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
152b0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
152c0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
152d0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
152e0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
152f0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
15300 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
15310 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
15320 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
15330 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15340 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
15350 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
15360 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
15370 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
15380 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
15390 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
153a0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
153b0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
153c0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
153d0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
153e0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
153f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
15400 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15410 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
15420 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
15430 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
15440 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
15450 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
15460 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
15470 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
15480 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
15490 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
154a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
154b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
154c0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
154d0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
154e0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
154f0 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33  ed on a [sqlite3
15500 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
15510 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
15520 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
15530 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
15540 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
15550 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
15560 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69  at had .** previ
15570 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
15580 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
15590 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
155a0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
155b0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
155c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
155d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
155e0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
155f0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
15600 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15610 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
15620 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
15630 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
15640 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20  :</b>.** In the 
15650 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
15660 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  , .** the sqlite
15670 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77  3_step() API alw
15680 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
15690 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
156a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
156b0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
156c0 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ny error other t
156d0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
156e0 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
156f0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
15700 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  ust call [sqlite
15710 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
15720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15730 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
15740 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
15750 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53  e specific.** [S
15760 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
15770 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74  sult codes] that
15780 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
15790 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
157a0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
157b0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
157c0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
157d0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
157e0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
157f0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
15800 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
15810 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
15820 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
15830 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
15840 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
15850 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
15860 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
15870 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
15880 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
15890 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
158a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
158b0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  )], then the .**
158c0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
158d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
158e0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
158f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
15900 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
15910 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
15920 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
15930 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
15940 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
15950 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
15960 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
15970 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a  ** CAPI3REF:.**.
15980 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
15990 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
159a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
159b0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
159c0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  set..**.** After
159d0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
159e0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74  te3_step()] that
159f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
15a00 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74  _ROW], this rout
15a10 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  ine.** will retu
15a20 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
15a30 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65  e as the [sqlite
15a40 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
15a50 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41  ] function..** A
15a60 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
15a70 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
15a80 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f  ed an [SQLITE_DO
15a90 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  NE], [SQLITE_BUS
15aa0 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c  Y], or.** a [SQL
15ab0 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
15ac0 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f  r code], or befo
15ad0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
15ae0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a  ()] has been .**
15af0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
15b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
15b10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15b20 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
15b30 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72   time,.** this r
15b40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
15b50 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ero..*/.int sqli
15b60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
15b70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
15b80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
15b90 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
15ba0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a  l Datatypes.**.*
15bb0 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  * Every value in
15bc0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
15bd0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
15be0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
15bf0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
15c00 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
15c10 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
15c20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
15c30 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
15c40 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
15c50 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
15c60 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
15c70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ul>.**.** These 
15c80 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
15c90 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
15ca0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
15cb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
15cc0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
15cd0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
15ce0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
15cf0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
15d00 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
15d10 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
15d20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
15d30 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
15d40 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
15d50 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
15d60 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
15d70 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
15d80 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  T not.** SQLITE_
15d90 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
15da0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
15db0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
15dc0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
15dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
15de0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
15df0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
15e00 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
15e10 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
15e20 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
15e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
15e40 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
15e50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
15e60 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
15e70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
15e80 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  lts Values From 
15e90 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  A Query.**.** Th
15ea0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15eb0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
15ec0 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c  about.** a singl
15ed0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
15ee0 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
15ef0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
15f00 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
15f10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
15f20 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
15f30 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
15f40 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
15f50 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
15f60 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
15f70 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
15f80 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
15f90 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
15fa0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
15fb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15fc0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
15fd0 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
15fe0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15ff0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
16000 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
16010 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
16020 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
16030 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
16040 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
16050 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
16060 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
16070 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
16080 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16090 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
160a0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
160b0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
160c0 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
160d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
160e0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
160f0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
16100 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
16110 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
16120 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
16130 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
16140 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
16150 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
16160 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
16170 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
16180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
16190 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
161a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
161b0 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
161c0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
161d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
161e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
161f0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
16200 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
16210 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
16220 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
16230 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
16240 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
16250 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
16260 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
16270 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
16280 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
16290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
162a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
162b0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
162c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
162d0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
162e0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
162f0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
16300 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
16310 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
16320 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
16330 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
16340 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
16350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
16360 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
16370 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
16380 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
16390 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
163a0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
163b0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
163c0 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
163d0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
163e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
163f0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
16400 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
16410 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
16420 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
16430 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
16440 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
16450 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
16460 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
16470 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
16480 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
16490 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
164a0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
164b0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
164c0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
164d0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
164e0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
164f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
16500 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
16510 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
16520 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16530 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
16540 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
16550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
16560 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
16570 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
16580 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
16590 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
165a0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
165b0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
165c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
165d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
165e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
165f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
16600 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
16610 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
16620 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
16630 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
16640 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
16650 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
16660 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
16670 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
16680 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16690 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
166a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
166b0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
166c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
166d0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
166e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
166f0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
16700 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
16710 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
16720 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
16730 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
16740 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
16750 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
16760 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
16770 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
16780 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
16790 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
167a0 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
167b0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
167c0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
167d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
167e0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
167f0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
16800 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
16810 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
16820 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
16830 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
16840 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
16850 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
16860 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  ven zero-length 
16870 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
16880 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
16890 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
168a0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
168b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
168c0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
168d0 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61  length blob is a
168e0 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
168f0 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
16900 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
16910 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
16920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16930 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
16940 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
16950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
16960 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
16970 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
16980 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64  n UTF-16 instead
16990 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20   of UTF-8.  .** 
169a0 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
169b0 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
169c0 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
169d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  t..**.** These r
169e0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
169f0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
16a00 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
16a10 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
16a20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
16a30 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
16a40 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
16a50 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
16a60 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
16a70 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
16a80 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
16a90 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64   internally to d
16aa0 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  o the conversion
16ab0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
16ac0 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
16ad0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
16ae0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  the conversions 
16af0 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c  that.** are appl
16b00 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
16b10 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
16b20 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
16b30 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
16b40 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
16b50 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
16b60 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
16b70 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
16b80 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
16b90 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
16ba0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
16bb0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
16bc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
16bd0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
16be0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
16bf0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
16c00 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
16c10 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
16c20 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
16c30 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
16c40 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
16c50 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
16c60 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
16c70 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
16c80 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
16c90 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
16ca0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
16cb0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
16cc0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
16cd0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
16ce0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
16cf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
16d00 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
16d10 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
16d20 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54  s for INTEGER->T
16d30 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
16d40 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
16d50 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
16d60 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
16d70 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
16d80 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
16d90 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
16da0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
16db0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
16dc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
16dd0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
16de0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
16df0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
16e00 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
16e10 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
16e20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
16e30 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
16e40 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
16e50 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
16e60 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
16e70 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
16e80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
16e90 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
16ea0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
16eb0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
16ec0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
16ed0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
16ee0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
16ef0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
16f00 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
16f10 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
16f20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
16f30 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
16f40 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
16f50 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
16f60 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
16f70 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
16f80 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
16f90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
16fa0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
16fb0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
16fc0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
16fd0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
16fe0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
16ff0 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
17000 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
17010 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
17020 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61  s its.** on equa
17030 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
17040 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
17050 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
17060 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
17070 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
17080 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
17090 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
170a0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
170b0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
170c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
170d0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
170e0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
170f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
17100 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
17110 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
17120 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
17130 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17140 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
17150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17160 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
17170 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20  nvalidated. .** 
17180 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
17190 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
171a0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
171b0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
171c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
171d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
171e0 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
171f0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
17200 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
17210 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
17220 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72   .**          or
17230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
17240 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
17250 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
17260 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
17270 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f           need to
17280 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
17290 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69   string.</p></li
172a0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
172b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
172c0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
172d0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
172e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
172f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
17300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
17310 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
17320 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
17330 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
17340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
17350 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e  UTF-16.</p></li>
17360 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  .**.** <li><p>  
17370 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
17380 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
17390 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
173a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
173b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
173c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
173d0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
173e0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
173f0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
17400 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
17410 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  8.</p></li>.** <
17420 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
17430 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
17440 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
17450 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
17460 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
17470 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
17480 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
17490 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
174a0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
174b0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
174c0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
174d0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
174e0 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
174f0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
17500 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
17510 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
17520 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
17530 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
17540 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
17550 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  e it is.** not p
17560 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
17570 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
17580 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
17590 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a  validated.  .**.
175a0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
175b0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
175c0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
175d0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
175e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
175f0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
17600 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
17610 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
17620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17630 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
17640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17650 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
17660 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
17670 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
17680 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
17690 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
176a0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
176b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
176c0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
176d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
176e0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  es16()</li>.**  
176f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
17700 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
17710 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
17720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
17730 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
17740 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20  n_blob(),.** or 
17750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17760 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
17770 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
17780 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  t into the desir
17790 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68  ed.** format, th
177a0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
177b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
177c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
177d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a  mn_bytes16() to.
177e0 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  ** find the size
177f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
17800 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
17810 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
17820 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
17830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17840 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
17850 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
17860 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41  mn_bytes16().  A
17870 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78  nd do not.** mix
17880 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
17890 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
178a0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
178b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
178c0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
178d0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
178e0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
178f0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
17900 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
17910 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
17920 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
17930 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
17940 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17950 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
17960 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
17970 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
17980 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
17990 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
179a0 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20  ** and blobs is 
179b0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
179c0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
179d0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
179e0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
179f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
17a00 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
17a10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
17a20 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
17a30 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
17a40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
17a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17a60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
17a70 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
17a80 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
17a90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
17aa0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
17ab0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
17ac0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
17ad0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
17ae0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
17af0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
17b00 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
17b10 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
17b20 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
17b30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
17b40 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
17b50 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
17b60 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e  E_NOMEM]..*/.con
17b70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
17b80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
17b90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17ba0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
17bb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
17bd0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
17be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
17bf0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
17c00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
17c10 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
17c20 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
17c30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
17c40 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
17c50 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
17c60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17c70 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
17c80 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
17c90 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
17ca0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17cb0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
17cc0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
17cd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
17ce0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17cf0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
17d00 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
17d10 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
17d20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17d30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17d40 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
17d50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
17d60 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
17d70 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
17d80 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
17d90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17db0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
17dc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
17dd0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
17de0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
17df0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
17e00 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
17e10 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e a .** [sqlite3
17e20 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
17e30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
17e40 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
17e50 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
17e60 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
17e70 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
17e80 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
17e90 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
17ea0 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
17eb0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
17ec0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
17ed0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
17ee0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
17ef0 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
17f00 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
17f10 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
17f20 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
17f30 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
17f40 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
17f50 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
17f60 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
17f70 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
17f80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76  sqlite3_stmt | v
17f90 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e  irtual machine].
17fa0 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
17fb0 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
17fc0 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65   .** completed e
17fd0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
17fe0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
17ff0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
18000 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
18010 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
18020 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53  n interrupt.  (S
18030 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  ee [sqlite3_inte
18040 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49  rrupt()].) .** I
18050 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
18060 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
18070 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
18080 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c  tions cancelled,
18090 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20    .** depending 
180a0 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
180b0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a  nces, and the .*
180c0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
180d0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72  | result code] r
180e0 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
180f0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
18100 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
18110 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
18120 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
18130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
18140 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
18150 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
18160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
18170 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
18180 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
18190 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71   reset a .** [sq
181a0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
181b0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
181c0 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  ent] object..** 
181d0 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69  back to it's ini
181e0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
181f0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
18200 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
18210 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
18220 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
18230 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
18240 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
18250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
18260 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
18270 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
18280 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
18290 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
182a0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
182b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
182c0 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73  ndings..*/.int s
182d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
182e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
182f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18300 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
18310 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
18320 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ions.**.** The f
18330 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
18340 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
18350 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
18360 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
18370 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65  es.** or to rede
18380 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
18390 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  r of existing SQ
183a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
183b0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a  ggregates.  The.
183c0 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e  ** difference on
183d0 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74  ly between the t
183e0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
183f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
18400 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
18410 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
18420 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
18430 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
18440 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  n UTF-8 for.** s
18450 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
18460 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
18470 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  -16 for sqlite3_
18480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
18490 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
184a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
184b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20   the [sqlite3 | 
184c0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
184d0 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a   that holds the.
184e0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
184f0 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20  or aggregate is 
18500 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72  to be added or r
18510 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73  edefined. If a s
18520 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  ingle.** program
18530 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
18540 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  one database han
18550 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  dle internally, 
18560 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
18570 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
18580 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  tes must be adde
18590 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
185a0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  o each database.
185b0 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  ** handle with w
185c0 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
185d0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
185e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
185f0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
18600 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
18610 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
18620 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
18630 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
18640 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
18650 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
18660 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
18670 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
18680 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
18690 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
186a0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
186b0 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
186c0 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
186d0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
186e0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
186f0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
18700 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
18710 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
18720 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
18730 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
18740 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
18750 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
18760 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
18770 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
18780 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
18790 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
187a0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
187b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
187c0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
187d0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
187e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
187f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
18800 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
18810 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
18820 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
18830 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
18840 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
18850 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
18860 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
18870 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
18880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
18890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
188a0 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
188b0 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
188c0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
188d0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
188e0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
188f0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
18900 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
18910 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
18920 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
18930 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
18940 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
18950 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
18960 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
18970 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
18980 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
18990 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
189a0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
189b0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
189c0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
189d0 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
189e0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
189f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
18a00 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
18a10 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
18a20 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
18a30 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
18a40 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
18a50 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
18a60 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
18a70 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
18a80 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
18a90 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
18aa0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
18ab0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
18ac0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
18ad0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
18ae0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
18af0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
18b00 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
18b10 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
18b20 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
18b30 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
18b40 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
18b50 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
18b60 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
18b70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
18b80 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
18b90 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
18ba0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
18bb0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
18bc0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
18bd0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
18be0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
18bf0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
18c00 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
18c10 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
18c20 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
18c30 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
18c40 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
18c50 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
18c60 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
18c70 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
18c80 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
18c90 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
18ca0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
18cb0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
18cc0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
18cd0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
18ce0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
18cf0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
18d00 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
18d10 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
18d20 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
18d30 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
18d40 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
18d50 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
18d60 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
18d70 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
18d80 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
18d90 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
18da0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
18db0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
18dc0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
18dd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
18de0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
18df0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
18e00 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
18e10 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
18e20 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
18e30 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
18e40 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
18e50 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
18e60 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
18e70 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
18e80 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
18e90 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
18ea0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
18eb0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
18ec0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69  on is used..*/.i
18ed0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18ee0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
18ef0 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74  lite3 *,.  const
18f00 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
18f10 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
18f20 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
18f30 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69  ,.  void*,.  voi
18f40 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
18f50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
18f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
18f70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
18f80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
18f90 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
18fa0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
18fb0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
18fc0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
18fd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18fe0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
18ff0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
19000 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
19010 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
19020 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
19030 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  p,.  void*,.  vo
19040 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
19050 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
19060 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
19070 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
19080 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
19090 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
190a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
190b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
190c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
190d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
190e0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
190f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
19100 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
19110 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
19120 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
19130 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
19140 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
19150 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
19160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
19170 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
19180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
19190 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
191a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
191b0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
191c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
191d0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
191e0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
191f0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
19200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
19210 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
19220 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
19230 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
19240 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19250 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
19260 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
19270 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
19280 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
19290 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
192a0 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
192b0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
192c0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
192d0 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
192e0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
192f0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
19300 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
19310 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
19320 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
19330 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
19340 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
19350 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
19360 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
19370 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
19380 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
19390 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
193a0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
193b0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
193c0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
193d0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
193e0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
193f0 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
19400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
19410 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
19420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
19430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
19440 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
19450 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
19460 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
19470 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
19480 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
19490 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
194a0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
194b0 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
194c0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
194d0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
194e0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
194f0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
19500 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
19510 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
19520 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
19530 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
19540 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
19550 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
19560 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
19570 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
19580 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
19590 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
195a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
195b0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
195c0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
195d0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
195e0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
195f0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
19600 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
19610 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
19620 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
19630 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
19640 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
19650 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
19660 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
19670 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
19680 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
19690 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
196a0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
196b0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
196c0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
196d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
196e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
196f0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
19700 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
19710 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
19720 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19730 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
19740 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
19750 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
19760 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
19770 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
19780 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
19790 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
197a0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
197b0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
197c0 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
197d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
197e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
197f0 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
19800 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
19810 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
19820 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
19830 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
19840 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
19850 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
19860 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
19870 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
19880 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
19890 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
198a0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
198b0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
198c0 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
198d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
198e0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
198f0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
19900 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
19910 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
19920 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
19930 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
19940 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
19950 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
19960 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
19970 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
19980 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
19990 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
199a0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
199b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
199c0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
199d0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
199e0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
199f0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
19a00 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
19a10 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
19a20 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
19a30 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
19a40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
19a50 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
19a60 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
19a70 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
19a80 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
19a90 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64  in order.** word
19aa0 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
19ab0 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72  s original a str
19ac0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
19ad0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
19ae0 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65   then it is done
19af0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
19b00 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
19b10 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
19b20 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
19b30 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
19b40 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
19b50 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
19b60 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
19b70 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
19b80 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
19b90 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
19ba0 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
19bb0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
19bc0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
19bd0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
19be0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
19bf0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
19c00 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
19c10 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
19c20 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
19c30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
19c40 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
19c50 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
19c60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
19c70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
19c80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
19c90 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a  text16()].  .**.
19ca0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19cb0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
19cc0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
19cd0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
19ce0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
19cf0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73  t supplied the s
19d00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61  qlite3_value* pa
19d10 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c  rameters..** Or,
19d20 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
19d30 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20  value* argument 
19d40 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  comes from the [
19d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
19d60 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  alue()].** inter
19d70 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65  face, then these
19d80 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
19d90 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
19da0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a  the same thread.
19db0 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c  ** that ran [sql
19dc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
19dd0 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  e()]..*/.const v
19de0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
19df0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
19e00 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
19e10 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
19e20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19e30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
19e40 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
19e50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
19e60 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
19e70 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
19e80 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
19e90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
19ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
19eb0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
19ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
19ed0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
19ee0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
19ef0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
19f00 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
19f10 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
19f20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
19f30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
19f40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
19f50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
19f60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
19f70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
19f80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
19f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19fa0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
19fb0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19fc0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
19fd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19fe0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19ff0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
1a000 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
1a010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a020 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
1a030 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
1a040 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  t.**.** The impl
1a050 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
1a060 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
1a070 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
1a080 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
1a090 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
1a0a0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
1a0b0 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20  eir state.  The 
1a0c0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1a0d0 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61  routine.** is ca
1a0e0 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
1a0f0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
1a100 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65   a new structure
1a110 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a   of size nBytes.
1a120 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c  ** is allocated,
1a130 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74   zeroed, and ret
1a140 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65  urned.  On subse
1a150 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72  quent calls (for
1a160 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67   the.** same agg
1a170 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29  regate instance)
1a180 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
1a190 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
1a1a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1a1b0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
1a1c0 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
1a1d0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
1a1e0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
1a1f0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  data..**.** The 
1a200 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64  buffer allocated
1a210 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
1a220 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  tically by SQLit
1a230 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65  e whan the aggre
1a240 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
1a250 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
1a260 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a270 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
1a280 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
1a290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1a2a0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
1a2b0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
1a2c0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1a2d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1a2e0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
1a2f0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
1a300 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
1a310 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
1a320 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
1a330 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1a340 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1a350 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
1a360 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
1a370 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1a380 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
1a390 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1a3a0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
1a3b0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
1a3c0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
1a3d0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
1a3e0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
1a3f0 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61  *.** The pUserDa
1a400 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ta parameter to 
1a410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
1a420 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
1a430 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
1a440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
1a450 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  6()] routines.**
1a460 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
1a470 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73  r user functions
1a480 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
1a490 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
1a4a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75  tation of the fu
1a4b0 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69  nction using thi
1a4c0 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s call..**.** Th
1a4d0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
1a4e0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
1a4f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1a500 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
1a510 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
1a520 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
1a530 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
1a540 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
1a550 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
1a560 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
1a570 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
1a580 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
1a590 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
1a5a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
1a5b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
1a5c0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
1a5d0 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
1a5e0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
1a5f0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
1a600 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
1a610 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
1a620 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1a630 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
1a640 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
1a650 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
1a660 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
1a670 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
1a680 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
1a690 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
1a6a0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
1a6b0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
1a6c0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
1a6d0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
1a6e0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
1a6f0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
1a700 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
1a710 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
1a720 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
1a730 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
1a740 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
1a750 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
1a760 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
1a770 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
1a780 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
1a790 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
1a7a0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
1a7b0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
1a7c0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
1a7d0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1a7e0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
1a7f0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
1a800 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
1a810 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
1a820 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
1a830 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
1a840 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
1a850 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1a860 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
1a870 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
1a880 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
1a890 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
1a8a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a8b0 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  Nth argument val
1a8c0 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ue to the curren
1a8d0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  t SQL function.*
1a8e0 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20  * call, where N 
1a8f0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1a900 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d  rameter. If no m
1a910 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65  eta-data has bee
1a920 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61  n set for.** tha
1a930 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20  t value, then a 
1a940 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1a950 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1a960 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
1a970 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65  auxdata() is use
1a980 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d  d to associate m
1a990 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e  eta-data with an
1a9a0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
1a9b0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74   argument. The t
1a9c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1a9d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1a9e0 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
1a9f0 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64  to be associated
1aa00 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73   with the Nth us
1aa10 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  er function argu
1aa20 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20  ment value. The 
1aa30 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
1aa40 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20  ter specifies a 
1aa50 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
1aa60 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f  will be called o
1aa70 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64  n the meta-.** d
1aa80 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72  ata pointer to r
1aa90 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69  elease it when i
1aaa0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1aab0 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20  equired. If the 
1aac0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69  .** destructor i
1aad0 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f  s NULL, it is no
1aae0 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  t invoked..**.**
1aaf0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
1ab00 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
1ab10 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
1ab20 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
1ab30 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
1ab40 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
1ab50 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ab60 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
1ab70 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
1ab80 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
1ab90 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
1aba0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1abb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
1abc0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
1abd0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
1abe0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
1abf0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
1ac00 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1ac10 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
1ac20 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
1ac30 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
1ac40 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
1ac50 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  text*, int, void
1ac60 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
1ac70 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
1ac80 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
1ac90 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
1aca0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
1acb0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
1acc0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
1acd0 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74  lue for the dest
1ace0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
1acf0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
1ad00 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
1ad10 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
1ad20 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
1ad30 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
1ad40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
1ad50 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
1ad60 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
1ad70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
1ad80 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
1ad90 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
1ada0 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
1adb0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
1adc0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
1add0 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a  troyed.  The .**
1ade0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
1adf0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
1ae00 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
1ae10 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
1ae20 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
1ae30 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
1ae40 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
1ae50 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
1ae60 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
1ae70 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
1ae80 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
1ae90 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
1aea0 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
1aeb0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
1aec0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
1aed0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
1aee0 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
1aef0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
1af00 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
1af10 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
1af20 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
1af30 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
1af40 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
1af50 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
1af60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1af70 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
1af80 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1af90 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
1afa0 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
1afb0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
1afc0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
1afd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1afe0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
1aff0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
1b000 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
1b010 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
1b020 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
1b030 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
1b040 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
1b050 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1b060 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
1b070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
1b080 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
1b090 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1b0a0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
1b0b0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
1b0c0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
1b0d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
1b0e0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
1b0f0 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
1b100 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
1b110 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
1b120 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
1b130 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
1b140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
1b150 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
1b160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b170 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1b180 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
1b190 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
1b1a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
1b1b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
1b1c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b1d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
1b1e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1b1f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
1b200 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
1b210 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
1b220 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
1b230 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  xception.  The.*
1b240 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  * parameter to s
1b250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b260 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
1b270 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1b280 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74  ).** is the text
1b290 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
1b2a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sage..**.** The 
1b2b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
1b2c0 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68  oobig() cause th
1b2d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
1b2e0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  mentation.** to 
1b2f0 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20  throw and error 
1b300 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
1b310 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
1b320 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
1b330 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
1b340 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b350 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1b360 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
1b370 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
1b380 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1b390 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
1b3a0 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
1b3b0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
1b3c0 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  r..*/.void sqlit
1b3d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
1b3e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b3f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1b400 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1b410 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b420 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
1b430 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b440 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
1b450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b460 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
1b470 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
1b480 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1b490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1b4a0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
1b4b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1b4c0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
1b4d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b4e0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
1b4f0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1b500 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b510 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
1b520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1b530 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b540 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
1b550 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
1b560 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b570 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
1b580 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1b590 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
1b5a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b5b0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
1b5c0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1b5d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1b5e0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1b5f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
1b600 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1b610 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1b620 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1b630 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1b640 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1b650 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1b660 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1b670 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1b680 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
1b690 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
1b6a0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
1b6b0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1b6c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1b6d0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
1b6e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1b6f0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
1b700 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1b710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1b720 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
1b730 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
1b740 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
1b750 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
1b760 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
1b770 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
1b780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1b790 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
1b7a0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
1b7b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1b7c0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
1b7d0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
1b7e0 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
1b7f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20  e.** [sqlite3*] 
1b800 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64  handle specified
1b810 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
1b820 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54  gument. .**.** T
1b830 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1b840 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1b850 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
1b860 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
1b870 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
1b880 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1b890 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
1b8a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b8b0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
1b8c0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
1b8d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
1b8e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1b8f0 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  .  In all cases.
1b900 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
1b910 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
1b920 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1b930 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
1b940 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1b950 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
1b960 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
1b970 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
1b980 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
1b990 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
1b9a0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
1b9b0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
1b9c0 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
1b9d0 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
1b9e0 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
1b9f0 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
1ba00 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
1ba10 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
1ba20 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
1ba30 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
1ba40 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1ba50 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
1ba60 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
1ba70 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1ba80 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
1ba90 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
1baa0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
1bab0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
1bac0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
1bad0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
1bae0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
1baf0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
1bb00 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20  ll it anymore). 
1bb10 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75 73  Each time the us
1bb20 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66  er.** supplied f
1bb30 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
1bb40 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
1bb50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1bb60 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a  oid* passed as.*
1bb70 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  * the fourth arg
1bb80 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1bb90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1bba0 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  n() or.** sqlite
1bbb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1bbc0 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69  on16() as its fi
1bbd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1bbe0 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  *.** The remaini
1bbf0 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
1bc00 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
1bc10 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
1bc20 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
1bc30 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
1bc40 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74  y a [length, dat
1bc50 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a] pair and enco
1bc60 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
1bc70 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
1bc80 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
1bc90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
1bca0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
1bcb0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
1bcc0 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 20  registered. The 
1bcd0 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68 6f  user routine sho
1bce0 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61 74  uld return negat
1bcf0 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
1bd00 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20  itive if.** the 
1bd10 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
1bd20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
1bd30 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
1bd40 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a  than the second.
1bd50 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  ** string. i.e. 
1bd60 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
1bd70 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
1bd80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1bd90 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
1bda0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1bdb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1bdc0 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61  ().** excapt tha
1bdd0 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
1bde0 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
1bdf0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
1be00 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
1be10 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
1be20 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
1be30 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
1be40 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
1be50 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
1be60 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
1be70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1be80 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
1be90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1bea0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1beb0 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61  ion_v2().  Colla
1bec0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
1bed0 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79  yed when.** they
1bee0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
1bef0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
1bf00 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
1bf10 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
1bf20 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  ns.** or when th
1bf30 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74  e [sqlite3*] dat
1bf40 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
1bf50 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
1bf60 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
1bf70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bf80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1bf90 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  on_v2() interfac
1bfa0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
1bfb0 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74  l and.** subject
1bfc0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1bfd0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20  ture releases.  
1bfe0 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74  The other collat
1bff0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20  ion creation.** 
1c000 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 74  functions are st
1c010 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  able..*/.int sql
1c020 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1c030 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
1c040 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1c050 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1c060 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1c070 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1c080 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1c090 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1c0a0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
1c0b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1c0c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
1c0d0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
1c0e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1c0f0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
1c100 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
1c110 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
1c120 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1c130 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1c140 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
1c150 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
1c160 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
1c170 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1c180 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1c190 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1c1a0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
1c1b0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
1c1c0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
1c1d0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1c1e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1c1f0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
1c200 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
1c210 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
1c220 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  backs.**.** To a
1c230 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
1c240 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
1c250 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1c260 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
1c270 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
1c280 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
1c290 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
1c2a0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
1c2b0 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
1c2c0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
1c2d0 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
1c2e0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
1c2f0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1c300 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
1c310 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
1c320 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
1c330 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
1c340 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1c350 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
1c360 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
1c370 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
1c380 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1c390 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
1c3a0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
1c3b0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 49  oded in UTF-8. I
1c3c0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
1c3d0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
1c3e0 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65  s used, the name
1c3f0 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  s.** are passed 
1c400 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
1c410 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
1c420 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74   order. A call t
1c430 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
1c440 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
1c450 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
1c460 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
1c470 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1c480 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
1c490 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
1c4a0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
1c4b0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
1c4c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c4d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1c4e0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
1c4f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c500 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63  ded16(). The sec
1c510 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1c520 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1c530 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72  handle. The thir
1c540 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
1c550 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
1c560 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
1c570 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  6BE], or.** [SQL
1c580 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
1c590 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
1c5a0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
1c5b0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
1c5c0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
1c5d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
1c5e0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
1c5f0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
1c600 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
1c610 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
1c620 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
1c630 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1c640 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
1c650 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
1c660 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
1c670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1c680 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
1c690 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1c6a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
1c6b0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1c6c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1c6d0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
1c6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1c6f0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
1c700 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
1c710 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
1c720 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
1c730 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
1c740 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
1c750 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1c760 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
1c770 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
1c780 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1c790 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1c7a0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
1c7b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
1c7c0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
1c7d0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
1c7e0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
1c7f0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
1c800 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
1c810 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
1c820 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
1c830 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
1c840 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
1c850 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1c860 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
1c870 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
1c880 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
1c890 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1c8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c8b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
1c8c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
1c8d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
1c8e0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
1c8f0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
1c900 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
1c910 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
1c920 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
1c930 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
1c940 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
1c950 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
1c960 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
1c970 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
1c980 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
1c990 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c9a0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
1c9b0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1c9c0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1c9d0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1c9e0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1c9f0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1ca00 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1ca10 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
1ca20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ca30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1ca40 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1ca50 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1ca60 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1ca70 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1ca80 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
1ca90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1caa0 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63  F:  Suspend Exec
1cab0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
1cac0 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  t Time.**.** Thi
1cad0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1cae0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
1caf0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
1cb00 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e  execution.** a n
1cb10 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
1cb20 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
1cb30 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
1cb40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
1cb50 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1cb60 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
1cb70 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
1cb80 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65  with .** millise
1cb90 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
1cba0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
1cbb0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
1cbc0 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68  ded up to .** th
1cbd0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
1cbe0 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
1cbf0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1cc00 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a  sleep actually .
1cc10 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
1cc20 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
1cc30 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
1cc40 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ed..**.** SQLite
1cc50 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
1cc60 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
1cc70 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
1cc80 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
1cc90 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1cca0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1ccb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ccc0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
1ccd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e  .** CAPI3REF:  N
1cce0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
1ccf0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
1cd00 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
1cd10 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
1cd20 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
1cd30 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
1cd40 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
1cd50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
1cd60 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72  older (a.ka. dir
1cd70 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
1cd80 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
1cd90 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
1cda0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
1cdb0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
1cdc0 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
1cdd0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
1cde0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
1cdf0 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20  hen SQLite does 
1ce00 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
1ce10 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70  appropriate temp
1ce20 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69  orary.** file di
1ce30 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
1ce40 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1ce50 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
1ce60 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74  iable once a dat
1ce70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ce80 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65  .** has been ope
1ce90 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65  ned.  It is inte
1cea0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
1ceb0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
1cec0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
1ced0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
1cee0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
1cef0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
1cf00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
1cf10 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
1cf20 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75  all and remain u
1cf30 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66  nchanged thereaf
1cf40 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ter..*/.SQLITE_E
1cf50 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
1cf60 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
1cf70 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
1cf80 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65  REF:  Test To Se
1cf90 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61 73  e If The Databas
1cfa0 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d  e Is In Auto-Com
1cfb0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54  mit Mode.**.** T
1cfc0 65 73 74 20 74 6f 20 73 65 65 20 77 68 65 74 68  est to see wheth
1cfd0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 64 61  er or not the da
1cfe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cff0 6e 20 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d  n is in autocomm
1d000 69 74 0a 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74  it.** mode.  Ret
1d010 75 72 6e 20 54 52 55 45 20 69 66 20 69 74 20 69  urn TRUE if it i
1d020 73 20 61 6e 64 20 46 41 4c 53 45 20 69 66 20 6e  s and FALSE if n
1d030 6f 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ot.  Autocommit 
1d040 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79  mode is on.** by
1d050 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63   default.  Autoc
1d060 6f 6d 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65  ommit is disable
1d070 64 20 62 79 20 61 20 42 45 47 49 4e 20 73 74 61  d by a BEGIN sta
1d080 74 65 6d 65 6e 74 20 61 6e 64 20 72 65 65 6e 61  tement and reena
1d090 62 6c 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e  bled.** by the n
1d0a0 65 78 74 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f  ext COMMIT or RO
1d0b0 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66  LLBACK..**.** If
1d0c0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
1d0d0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
1d0e0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
1d0f0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
1d100 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
1d110 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69  ctions (errors i
1d120 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
1d130 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
1d140 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  IOERR], .** [SQL
1d150 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
1d160 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
1d170 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1d180 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
1d190 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
1d1a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1d1b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
1d1c0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
1d1d0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53  ** find out if S
1d1e0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
1d1f0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
1d200 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
1d210 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
1d220 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
1d230 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1d240 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
1d250 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
1d260 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
1d270 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1d280 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
1d290 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
1d2a0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
1d2b0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1d2c0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
1d2d0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
1d2e0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
1d2f0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
1d300 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1d310 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
1d320 65 20 48 61 6e 64 6c 65 20 41 73 73 6f 63 69 61  e Handle Associa
1d330 74 65 64 20 57 69 74 68 20 41 20 50 72 65 70 61  ted With A Prepa
1d340 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
1d350 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 5b  .** Return the [
1d360 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
1d370 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69  se handle to whi
1d380 63 68 20 61 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ch a.** [sqlite3
1d390 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
1d3a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
1d3b0 6e 67 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ngs..** This is 
1d3c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1d3d0 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
1d3e0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
1d3f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
1d400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d410 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1d420 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
1d430 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
1d440 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1d450 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
1d460 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
1d470 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
1d480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1d490 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1d4a0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
1d4b0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
1d4c0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1d4d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d4e0 65 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 20 63  es.** register c
1d4f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d500 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
1d510 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
1d520 61 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d  action.** is com
1d530 6d 69 74 74 65 64 20 6f 72 20 72 6f 6c 6c 65 64  mitted or rolled
1d540 20 62 61 63 6b 2e 20 20 54 68 65 20 70 41 72 67   back.  The pArg
1d550 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
1d560 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74  sed through.** t
1d570 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  o the callback. 
1d580 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
1d590 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
1d5a0 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72  k function .** r
1d5b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1d5c0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
1d5d0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
1d5e0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
1d5f0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
1d600 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
1d610 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1d620 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
1d630 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ue is returned..
1d640 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  ** Otherwise NUL
1d650 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
1d660 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
1d670 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
1d680 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
1d690 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f  llback..**.** Fo
1d6a0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
1d6b0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
1d6c0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
1d6d0 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a  d to have been .
1d6e0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
1d6f0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
1d700 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
1d710 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
1d720 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
1d730 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
1d740 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
1d750 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
1d760 72 2e 20 54 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  r. The .** callb
1d770 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
1d780 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
1d790 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
1d7a0 61 6c 6c 79 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62  ally rolled.** b
1d7b0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
1d7c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d7d0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1d7e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65  *.** These are e
1d7f0 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
1d800 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73  rfaces and are s
1d810 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1d820 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1d830 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
1d840 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1d850 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1d860 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
1d870 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
1d880 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
1d890 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
1d8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d8b0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
1d8c0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
1d8d0 6b 73 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  ks.**.** Registe
1d8e0 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
1d8f0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64  ction with the d
1d900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d910 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  on identified by
1d920 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61   the .** first a
1d930 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e  rgument to be in
1d940 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
1d950 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
1d960 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
1d970 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
1d980 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
1d990 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
1d9a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f  this function fo
1d9b0 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64  r the same .** d
1d9c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d9d0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
1d9e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1d9f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
1da00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1da10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
1da20 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f  ke when a .** ro
1da30 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
1da40 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
1da50 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
1da60 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
1da70 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f  lback is.** a co
1da80 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
1da90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1daa0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
1dab0 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ). The second ca
1dac0 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d  llback .** argum
1dad0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 53 51  ent is one of SQ
1dae0 4c 49 54 45 5f 49 4e 53 45 52 54 2c 20 53 51 4c  LITE_INSERT, SQL
1daf0 49 54 45 5f 44 45 4c 45 54 45 20 6f 72 20 53 51  ITE_DELETE or SQ
1db00 4c 49 54 45 5f 55 50 44 41 54 45 2c 20 64 65 70  LITE_UPDATE, dep
1db10 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 74 68 65  ending.** on the
1db20 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1db30 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
1db40 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
1db50 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  d. The third and
1db60 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75   .** fourth argu
1db70 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
1db80 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
1db90 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64 61  inters to the da
1dba0 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74  tabase and .** t
1dbb0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
1dbc0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
1dbd0 64 20 72 6f 77 2e 20 54 68 65 20 66 69 6e 61 6c  d row. The final
1dbe0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
1dbf0 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72  ter is .** the r
1dc00 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e  owid of the row.
1dc10 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
1dc20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
1dc30 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
1dc40 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74  er .** the updat
1dc50 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
1dc60 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
1dc70 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
1dc80 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
1dc90 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
1dca0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
1dcb0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
1dcc0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
1dcd0 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20  equence)..**.** 
1dce0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
1dcf0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
1dd00 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
1dd10 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
1dd20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
1dd30 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
1dd40 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  returned..*/.voi
1dd50 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
1dd60 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
1dd70 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
1dd80 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
1dd90 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
1dda0 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
1ddb0 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
1ddc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ddd0 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
1dde0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
1ddf0 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 54 68 69   Cache.**.** Thi
1de00 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
1de10 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
1de20 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
1de30 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
1de40 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
1de50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
1de60 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e  tween connection
1de70 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  s to the same da
1de80 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69  tabase..** Shari
1de90 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
1dea0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
1deb0 20 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c   true and disabl
1dec0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
1ded0 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a  nt.** is false..
1dee0 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20  **.** Beginning 
1def0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
1df00 6e 20 33 2e 35 2e 30 2c 20 63 61 63 68 65 20 73  n 3.5.0, cache s
1df10 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
1df20 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a  d and disabled.*
1df30 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  * for an entire 
1df40 70 72 6f 63 65 73 73 2e 20 20 49 6e 20 70 72 69  process.  In pri
1df50 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
1df60 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77  QLite, sharing w
1df70 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
1df80 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
1df90 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
1dfa0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
1dfb0 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
1dfc0 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
1dfd0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
1dfe0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
1dff0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
1e000 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e020 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1e030 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
1e040 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
1e050 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
1e060 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
1e070 72 69 6e 67 20 6d 6f 64 65 20 74 68 61 74 20 77  ring mode that w
1e080 61 73 0a 2a 2a 20 69 6e 20 65 66 66 65 63 74 20  as.** in effect 
1e090 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
1e0a0 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
1e0b0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
1e0c0 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
1e0d0 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
1e0e0 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61  cache.  When sha
1e0f0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1e100 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
1e110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
1e120 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20  ule()] API used 
1e130 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
1e140 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
1e150 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
1e160 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
1e170 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1e180 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1e190 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
1e1a0 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  e was.** enabled
1e1b0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
1e1c0 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
1e1d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
1e1e0 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
1e1f0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
1e200 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
1e210 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
1e220 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
1e230 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
1e240 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
1e250 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1e260 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
1e270 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
1e280 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
1e290 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
1e2a0 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
1e2b0 69 63 69 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20 73  icitly..*/.int s
1e2c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1e2d0 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
1e2e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e2f0 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72  :  Attempt To Fr
1e300 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a  ee Heap Memory.*
1e310 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20  *.** Attempt to 
1e320 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
1e330 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
1e340 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
1e350 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d  essential.** mem
1e360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
1e370 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
1e380 62 61 73 65 20 6c 69 62 72 61 72 79 20 28 65 78  base library (ex
1e390 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a  ample: memory .*
1e3a0 2a 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  * used to cache 
1e3b0 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74  database pages t
1e3c0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
1e3d0 6d 61 6e 63 65 29 2e 0a 2a 2f 0a 69 6e 74 20 73  mance)..*/.int s
1e3e0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
1e3f0 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
1e400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d  ** CAPI3REF:  Im
1e410 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
1e420 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20  Heap Size.**.** 
1e430 50 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20 6c  Place a "soft" l
1e440 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
1e450 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
1e460 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
1e470 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51  located.** by SQ
1e480 4c 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e 74  Lite.  If an int
1e490 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e  ernal allocation
1e4a0 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a   is requested .*
1e4b0 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  * that would exc
1e4c0 65 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65  eed the specifie
1e4d0 64 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65  d limit, [sqlite
1e4e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
1e4f0 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65  ()] is.** invoke
1e500 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
1e510 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73  mes to free up s
1e520 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65  ome space before
1e530 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a   the allocation.
1e540 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  ** is made..**.*
1e550 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63  * The limit is c
1e560 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
1e570 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65  cause if [sqlite
1e580 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
1e590 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72  ()] cannot.** fr
1e5a0 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
1e5b0 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
1e5c0 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
1e5d0 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
1e5e0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
1e5f0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
1e600 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
1e610 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1e620 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  eds..**.** A neg
1e630 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
1e640 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
1e650 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
1e660 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
1e670 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1e680 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1e690 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
1e6a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
1e6b0 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
1e6c0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1e6d0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
1e6e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
1e6f0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
1e700 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
1e710 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
1e720 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
1e730 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74  imit.  But if it
1e740 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  .** is unable to
1e750 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
1e760 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73  sage below the s
1e770 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75  oft limit, execu
1e780 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
1e790 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
1e7a0 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
1e7b0 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
1e7c0 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a  y the limit is .
1e7d0 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66  ** called a "sof
1e7e0 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73  t" limit.  It is
1e7f0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
1e800 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 66 74 20 68  **.** The soft h
1e810 65 61 70 20 6c 69 6d 69 74 20 69 73 20 69 6d 70  eap limit is imp
1e820 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 74  lemented using t
1e830 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1e840 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69  ry_alarm()].** i
1e850 6e 74 65 72 66 61 63 65 2e 20 20 4f 6e 6c 79 20  nterface.  Only 
1e860 61 20 73 69 6e 67 6c 65 20 6d 65 6d 6f 72 79 20  a single memory 
1e870 61 6c 61 72 6d 20 69 73 20 61 76 61 69 6c 61 62  alarm is availab
1e880 6c 65 20 69 6e 20 74 68 65 20 64 65 66 61 75 6c  le in the defaul
1e890 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  t.** implementat
1e8a0 69 6f 6e 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  ion.  This means
1e8b0 20 74 68 61 74 20 69 66 20 74 68 65 20 61 70 70   that if the app
1e8c0 6c 69 63 61 74 69 6f 6e 20 61 6c 73 6f 20 75 73  lication also us
1e8d0 65 73 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  es the.** memory
1e8e0 20 61 6c 61 72 6d 20 69 6e 74 65 72 66 61 63 65   alarm interface
1e8f0 20 69 74 20 77 69 6c 6c 20 69 6e 74 65 72 66 65   it will interfe
1e900 72 65 20 77 69 74 68 20 74 68 65 20 6f 70 65 72  re with the oper
1e910 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
1e920 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
1e930 61 6e 64 20 75 6e 64 65 66 69 6e 65 64 20 62 65  and undefined be
1e940 68 61 76 69 6f 72 20 77 69 6c 6c 20 72 65 73 75  havior will resu
1e950 6c 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  lt.  .**.** Prio
1e960 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1e970 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
1e980 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
1e990 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
1e9a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
1e9b0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
1e9c0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
1e9d0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
1e9e0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
1e9f0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
1ea00 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
1ea10 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
1ea20 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
1ea30 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
1ea40 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20 54 68  all threads.  Th
1ea50 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
1ea60 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
1ea70 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
1ea80 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
1ea90 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
1eaa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
1eab0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20  r all threads.  
1eac0 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
1ead0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
1eae0 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
1eaf0 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
1eb00 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
1eb10 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
1eb20 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1eb30 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
1eb40 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1eb50 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63 74  PI3REF:  Extract
1eb60 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
1eb70 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
1eb80 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ble.**.** This r
1eb90 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e  outine.** return
1eba0 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75  s meta-data abou
1ebb0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
1ebc0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
1ebd0 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  c database.** ta
1ebe0 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
1ebf0 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1ec00 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65  ion handle passe
1ec10 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
1ec20 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75  unction .** argu
1ec30 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
1ec40 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
1ec50 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
1ec60 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
1ec70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
1ec80 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  to .** this func
1ec90 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
1eca0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
1ecb0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
1ecc0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1ecd0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
1ece0 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
1ecf0 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
1ed00 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
1ed10 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
1ed20 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
1ed30 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
1ed40 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
1ed50 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
1ed60 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
1ed70 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
1ed80 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74  e algorithm as t
1ed90 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
1eda0 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72  ne uses to .** r
1edb0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
1edc0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
1edd0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
1ede0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
1edf0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ee00 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
1ee10 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
1ee20 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66  lumn .** name of
1ee30 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
1ee40 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
1ee50 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
1ee60 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a  ese parameters .
1ee70 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
1ee80 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72  **.** Meta infor
1ee90 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  mation is return
1eea0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
1eeb0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
1eec0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a  tions passed as.
1eed0 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73  ** the 5th and s
1eee0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
1eef0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
1ef00 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68  ction. Any of th
1ef10 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ese .** argument
1ef20 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69  s may be NULL, i
1ef30 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
1ef40 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
1ef50 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a  lement of meta .
1ef60 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1ef70 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  s ommitted..**.*
1ef80 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d  * <pre>.** Param
1ef90 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20  eter     Output 
1efa0 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69  Type      Descri
1efb0 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d  ption.** -------
1efc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1efd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a  ------------.**.
1efe0 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20  **   5th        
1eff0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
1f000 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20    Data type.**  
1f010 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   6th         con
1f020 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61  st char*      Na
1f030 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  me of the defaul
1f040 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
1f050 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20  ence .**   7th  
1f060 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
1f070 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
1f080 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61  the column has a
1f090 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
1f0a0 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20  aint.**   8th   
1f0b0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
1f0c0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
1f0d0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  he column is par
1f0e0 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
1f0f0 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20   KEY.**   9th   
1f100 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
1f110 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
1f120 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54  he column is AUT
1f130 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f  OINCREMENT.** </
1f140 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  pre>.**.**.** Th
1f150 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
1f160 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
1f170 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
1f180 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a  turned for the .
1f190 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
1f1a0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
1f1b0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
1f1c0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
1f1d0 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c  he next .** call
1f1e0 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41   to any sqlite A
1f1f0 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
1f200 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
1f210 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
1f220 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68  ually a view, th
1f230 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  en an error is r
1f240 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
1f250 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
1f260 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
1f270 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
1f280 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a  wid_" and an .**
1f290 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
1f2a0 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20   KEY column has 
1f2b0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
1f2c0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
1f2d0 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61  he output .** pa
1f2e0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
1f2f0 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
1f300 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
1f310 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
1f320 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
1f330 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63  y declared IPK c
1f340 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
1f350 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72  output parameter
1f360 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a  s are set as .**
1f370 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1f380 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
1f390 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
1f3a0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
1f3b0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
1f3c0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
1f3d0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
1f3e0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
1f3f0 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
1f400 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
1f410 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
1f420 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
1f430 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
1f440 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
1f450 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
1f460 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
1f470 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
1f480 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
1f490 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
1f4a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
1f4b0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51   be found, an SQ
1f4c0 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20  LITE error code 
1f4d0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
1f4e0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1f4f0 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20  .** left in the 
1f500 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
1f510 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
1f520 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
1f530 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20  rrmsg())..**.** 
1f540 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
1f550 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
1f560 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
1f570 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
1f580 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
1f590 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
1f5a0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
1f5b0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
1f5c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
1f5d0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
1f5e0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
1f5f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
1f600 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
1f610 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f620 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
1f630 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f640 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
1f650 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f660 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
1f670 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
1f680 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f690 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
1f6a0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
1f6b0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
1f6c0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
1f6d0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
1f6e0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
1f6f0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
1f700 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
1f710 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
1f720 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
1f730 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
1f740 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
1f750 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
1f760 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
1f770 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
1f780 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
1f790 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
1f7a0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
1f7b0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
1f7c0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
1f7d0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
1f7e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
1f7f0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
1f800 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
1f810 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
1f820 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
1f830 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
1f840 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 6c  .** Attempt to l
1f850 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78  oad an SQLite ex
1f860 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
1f870 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
1f880 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20   file.** zFile. 
1f890 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   The entry point
1f8a0 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50 72 6f   is zProc.  zPro
1f8b0 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20 77 68  c may be 0 in wh
1f8c0 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  ich case the.** 
1f8d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
1f8e0 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73  y point defaults
1f8f0 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
1f900 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
1f910 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51 4c 49  .** Return [SQLI
1f920 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
1f930 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
1f940 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
1f950 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
1f960 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20  .** If an error 
1f970 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
1f980 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
1f990 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  en fill *pzErrMs
1f9a0 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72  g with .** error
1f9b0 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e 20 20   message text.  
1f9c0 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
1f9d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65  tion should free
1f9e0 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20   this memory.** 
1f9f0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1fa00 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
1fa10 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** Extension loa
1fa20 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
1fa30 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1fa40 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1fa50 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
1fa60 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1fa70 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20   this API or an 
1fa80 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
1fa90 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
1faa0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
1fab0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
1fac0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1fad0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
1fae0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
1faf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fb00 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
1fb10 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
1fb20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
1fb30 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
1fb40 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
1fb50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1fb60 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
1fb70 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
1fb80 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
1fb90 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
1fba0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
1fbb0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
1fbc0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
1fbd0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
1fbe0 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
1fbf0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1fc00 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
1fc10 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
1fc20 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
1fc30 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
1fc40 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1fc50 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
1fc60 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
1fc70 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
1fc80 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
1fc90 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
1fca0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
1fcb0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
1fcc0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
1fcd0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
1fce0 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70  wing.** API is p
1fcf0 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
1fd00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
1fd10 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
1fd20 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a  echanism on and.
1fd30 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73 20 6f  ** off.  It is o
1fd40 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ff by default.  
1fd50 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
1fd60 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69  ..**.** Call thi
1fd70 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f  s routine with o
1fd80 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20  noff==1 to turn 
1fd90 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
1fda0 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c  g on.** and call
1fdb0 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
1fdc0 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63  0 to turn it bac
1fdd0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
1fde0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
1fdf0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
1fe00 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
1fe10 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
1fe20 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65  * CAPI3REF: Make
1fe30 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f   Arrangements To
1fe40 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
1fe50 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
1fe60 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20  .**.** Register 
1fe70 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
1fe80 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
1fe90 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
1fea0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
1feb0 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  er a new databas
1fec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1fed0 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  opened using.** 
1fee0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1fef0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1ff00 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
1ff10 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
1ff20 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e  .** This API can
1ff30 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked at p
1ff40 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69  rogram startup i
1ff50 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73  n order to regis
1ff60 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
1ff70 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69  re statically li
1ff80 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20  nked extensions 
1ff90 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61  that will be ava
1ffa0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c  ilable.** to all
1ffb0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1ffc0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
1ffd0 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
1ffe0 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
1fff0 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
20000 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
20010 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
20020 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
20030 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
20040 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
20050 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
20060 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
20070 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
20080 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62  ay.** that is ob
20090 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c  tained from mall
200a0 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75  oc().  If you ru
200b0 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a  n a memory leak.
200c0 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f  ** checker on yo
200d0 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69  ur program and i
200e0 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b  t reports a leak
200f0 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   because of this
20100 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20  .** array, then 
20110 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
20120 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73  automatic_extens
20130 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70 72 69  ion_reset()] pri
20140 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
20150 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
20160 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 74 6f  mory..**.** Auto
20170 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
20180 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c   apply across al
20190 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
201a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
201b0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
201c0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
201d0 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
201e0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
201f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
20200 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
20210 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
20220 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50  on(void *xEntryP
20230 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  oint);.../*.** C
20240 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
20250 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
20260 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
20270 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70 72 65   Disable all pre
20280 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
20290 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ed automatic ext
202a0 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73 0a 2a  ensions.  This.*
202b0 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
202c0 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61   the effect of a
202d0 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65  ll prior [sqlite
202e0 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65  3_automatic_exte
202f0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  nsion()].** call
20300 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 63 61  s..**.** This ca
20310 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f  ll disabled auto
20320 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
20330 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
20340 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
20350 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
20360 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
20370 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
20380 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
20390 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
203a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
203b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  id sqlite3_reset
203c0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
203d0 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a  void);.../*.****
203e0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
203f0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
20400 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
20410 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
20420 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  *.**.** The inte
20430 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
20440 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
20450 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
20460 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
20470 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
20480 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
20490 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
204a0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
204b0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
204c0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
204d0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
204e0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
204f0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
20500 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
20510 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
20520 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20  nism stablizes, 
20530 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
20540 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
20550 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
20560 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
20570 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
20580 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
20590 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
205a0 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
205b0 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
205c0 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
205d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
205e0 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
205f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20600 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
20610 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
20620 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
20630 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
20640 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
20650 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
20660 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
20670 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
20680 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
20690 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61  ** A module is a
206a0 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61   class of virtua
206b0 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20  l tables.  Each 
206c0 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65  module is define
206d0 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61  d.** by an insta
206e0 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  nce of the follo
206f0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20  wing structure. 
20700 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
20710 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74  consists.** most
20720 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
20730 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  r the module..*/
20740 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
20750 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
20760 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
20770 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
20780 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
20790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
207a0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
207b0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
207c0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
207d0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
207e0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
207f0 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
20800 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
20810 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
20820 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
20830 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
20840 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
20850 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
20860 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
20870 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
20880 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
20890 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
208a0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
208b0 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
208c0 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
208d0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
208e0 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
208f0 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
20900 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
20910 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
20920 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
20930 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
20940 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
20950 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
20960 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
20970 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
20980 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
20990 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
209a0 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
209b0 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
209c0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
209d0 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
209e0 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
209f0 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
20a00 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
20a10 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
20a20 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
20a30 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
20a40 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
20a50 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
20a60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
20a70 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
20a80 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
20a90 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
20aa0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
20ab0 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
20ac0 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
20ad0 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
20ae0 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
20af0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
20b00 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
20b10 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
20b20 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
20b30 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
20b40 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
20b50 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
20b60 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
20b70 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
20b80 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
20b90 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
20ba0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
20bb0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
20bc0 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
20bd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
20be0 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
20bf0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
20c00 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
20c10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
20c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
20c30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
20c40 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
20c50 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28  ppArg);..  int (
20c60 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
20c70 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
20c80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
20c90 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ;.};../*.** The 
20ca0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
20cb0 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  fo structure and
20cc0 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72   its substructur
20cd0 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a  es is used to.**
20ce0 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
20cf0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
20d00 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
20d10 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78  m the xBestIndex
20d20 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  .** method of an
20d30 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e   sqlite3_module.
20d40 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
20d50 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
20d60 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
20d70 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
20d80 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
20d90 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
20da0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
20db0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
20dc0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
20dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  .**.** The aCons
20de0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
20df0 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
20e00 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
20e10 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a  of the.** form:.
20e20 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f  **.**         co
20e30 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a  lumn OP expr.**.
20e40 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d  ** Where OP is =
20e50 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20 3e  , <, <=, >, or >
20e60 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c  =.  The particul
20e70 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73  ar operator is s
20e80 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e  tored.** in aCon
20e90 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
20ea0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
20eb0 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
20ec0 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61   in .** aConstra
20ed0 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20  int[].iColumn.  
20ee0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
20ef0 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
20f00 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
20f10 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
20f20 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
20f30 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
20f40 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
20f50 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
20f60 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
20f70 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74  t..**.** The opt
20f80 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
20f90 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
20fa0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
20fb0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
20fc0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
20fd0 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
20fe0 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
20ff0 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
21000 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
21010 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
21020 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
21030 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
21040 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
21050 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
21060 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
21070 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
21080 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74  lause terms in t
21090 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f  he correct.** fo
210a0 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f  rm that refer to
210b0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
210c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
210d0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
210e0 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** Information a
210f0 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
21100 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
21110 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
21120 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f  ..** Each term o
21130 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72  f aOrderBy recor
21140 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ds a column of t
21150 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
21160 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42  se..**.** The xB
21170 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
21180 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
21190 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
211a0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
211b0 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
211c0 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
211d0 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
211e0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
211f0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
21200 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
21210 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
21220 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
21230 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
21240 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
21250 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
21260 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
21270 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
21280 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
21290 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
212a0 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
212b0 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
212c0 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
212d0 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
212e0 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
212f0 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
21300 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
21310 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
21320 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
21330 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69   passed into xFi
21340 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  lter..** sqlite3
21350 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20  _free() is used 
21360 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
21370 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  f needToFreeIdxP
21380 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
21390 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  * The orderByCon
213a0 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
213b0 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69   output from xFi
213c0 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20  lter will occur 
213d0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
213e0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
213f0 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
21400 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
21410 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
21420 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
21430 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
21440 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
21450 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
21460 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
21470 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
21480 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
21490 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
214a0 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
214b0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
214c0 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
214d0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
214e0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
214f0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
21500 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
21510 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
21520 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
21530 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
21540 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
21550 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
21560 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
21570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
21580 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
21590 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
215a0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
215b0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
215c0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
215d0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
215e0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
215f0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
21600 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
21610 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
21620 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
21630 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
21640 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
21650 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
21660 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
21670 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
21680 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
21690 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
216a0 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
216b0 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
216c0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
216d0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
216e0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
216f0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
21700 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
21710 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
21720 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
21730 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
21740 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
21750 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
21760 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
21770 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
21780 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
21790 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
217a0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
217b0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
217c0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
217d0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
217e0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
217f0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
21800 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
21810 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
21820 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
21830 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a  R BY clause */..
21840 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
21850 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
21860 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
21870 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
21880 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
21890 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
218a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
218b0 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
218c0 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
218d0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
218e0 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
218f0 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
21900 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
21910 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
21920 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
21930 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
21940 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
21950 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
21960 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
21970 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
21980 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21990 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
219a0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
219b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
219c0 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
219d0 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
219e0 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
219f0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
21a00 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
21a10 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
21a20 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
21a30 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
21a40 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
21a50 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
21a60 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
21a70 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
21a80 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
21a90 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69  ndex */.};.#defi
21aa0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
21ab0 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
21ac0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
21ad0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
21ae0 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
21af0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
21b00 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
21b10 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
21b20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
21b30 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
21b40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
21b50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
21b60 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
21b70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
21b80 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
21b90 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
21ba0 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
21bb0 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64 75  ister a new modu
21bc0 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e 20  le name with an 
21bd0 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63  SQLite.** connec
21be0 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e 61  tion.  Module na
21bf0 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67 69  mes must be regi
21c00 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63 72  stered before cr
21c10 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76 69  eating new.** vi
21c20 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e 20  rtual tables on 
21c30 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62  the module, or b
21c40 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65 65  efore using pree
21c50 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c 0a  xisting virtual.
21c60 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68 65  ** tables of the
21c70 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20   module..*/.int 
21c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
21c90 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
21ca0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
21cb0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
21cc0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
21cd0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
21ce0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
21cf0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
21d00 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
21d10 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
21d20 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
21d30 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
21d40 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
21d50 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20 20   */.  void *    
21d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21d70 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
21d80 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
21d90 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  nect */.);../*.*
21da0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
21db0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74  s identical to t
21dc0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
21dd0 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74 68 6f  e_module() metho
21de0 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65  d above,.** exce
21df0 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 77  pt that it allow
21e00 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
21e10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 73 70  unction to be sp
21e20 65 63 69 66 69 65 64 2e 20 49 74 20 69 73 0a 2a  ecified. It is.*
21e30 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78 70 65  * even more expe
21e40 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20 74 68  rimental than th
21e50 65 20 72 65 73 74 20 6f 66 20 74 68 65 20 76 69  e rest of the vi
21e60 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41 50 49  rtual tables API
21e70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21e80 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
21e90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
21ea0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
21eb0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
21ec0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
21ed0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
21ee0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
21ef0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
21f00 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
21f10 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
21f20 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
21f30 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
21f40 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
21f50 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
21f60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
21f70 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
21f80 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
21f90 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
21fa0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
21fb0 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
21fc0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
21fd0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 76 65 72  /.);../*.** Ever
21fe0 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  y module impleme
21ff0 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
22000 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66  ubclass of the f
22010 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
22020 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62  re.** to describ
22030 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
22040 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d  nstance of the m
22050 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62  odule.  Each sub
22060 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
22070 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65   tailored to the
22080 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
22090 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
220a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20  plementation.   
220b0 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f  The.** purpose o
220c0 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
220d0 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
220e0 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
220f0 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a  at are common.**
22100 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
22110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
22120 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
22130 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
22140 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
22150 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
22160 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
22170 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
22180 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 74  ite3_mprintf() t
22190 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
221a0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
221b0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
221c0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
221d0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
221e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  all to sqlite3_f
221f0 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74  ree().** prior t
22200 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65  o assigning a ne
22210 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72  w string to zErr
22220 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68 65 20  Msg.  After the 
22230 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
22240 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
22250 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
22260 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
22270 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
22280 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
22290 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
222a0 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
222b0 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
222c0 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e  ll be zeroed.  N
222d0 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69  ote.** that sqli
222e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
222f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  d sqlite3_free()
22300 20 61 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65   are used on the
22310 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a   zErrMsg field.*
22320 2a 20 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20  * since virtual 
22330 74 61 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f  tables are commo
22340 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  nly implemented 
22350 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65  in loadable exte
22360 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20  nsions which.** 
22370 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  do not have acce
22380 73 73 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72  ss to sqlite3MPr
22390 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65  intf() or sqlite
223a0 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75  3Free()..*/.stru
223b0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
223c0 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
223d0 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
223e0 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
223f0 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
22400 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
22410 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
22420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
22430 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
22440 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72   */.  char *zErr
22450 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20  Msg;            
22460 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
22470 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69  essage from sqli
22480 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f  te3_mprintf() */
22490 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
224a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
224b0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
224c0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
224d0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
224e0 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20  /* Every module 
224f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
22500 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
22510 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
22520 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20  structure.** to 
22530 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
22540 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
22550 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
22560 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  le and are used.
22570 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
22580 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
22590 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
225a0 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
225b0 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65   the.** xOpen me
225c0 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
225d0 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
225e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
225f0 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
22600 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
22610 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
22620 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
22630 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
22640 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
22650 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
22660 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
22670 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
22680 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
22690 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
226a0 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
226b0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
226c0 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
226d0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
226e0 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
226f0 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
22700 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
22710 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
22720 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
22730 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
22740 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
22750 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  /.};../*.** The 
22760 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e  xCreate and xCon
22770 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20  nect methods of 
22780 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65  a module use the
22790 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
227a0 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
227b0 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
227c0 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
227d0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
227e0 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
227f0 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
22800 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74  mplement..*/.int
22810 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
22820 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
22830 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65  const char *zCre
22840 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a  ateTable);../*.*
22850 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
22860 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
22870 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
22880 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
22890 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
228a0 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  he xFindFunction
228b0 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c   method.  But gl
228c0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
228d0 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
228e0 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
228f0 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
22900 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
22910 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73  This API makes s
22920 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72  ure a global ver
22930 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69  sion of a functi
22940 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63  on with a partic
22950 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64  ular.** name and
22960 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
22970 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49  eters exists.  I
22980 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69  f no such functi
22990 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66  on exists.** bef
229a0 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20  ore this API is 
229b0 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75  called, a new fu
229c0 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  nction is create
229d0 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
229e0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
229f0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
22a00 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
22a10 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
22a20 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
22a30 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
22a40 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
22a50 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
22a60 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
22a70 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
22a80 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20   a place-holder 
22a90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
22aa0 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a  n be overloaded.
22ab0 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74 61  ** by virtual ta
22ac0 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bles..**.** This
22ad0 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63   API should be c
22ae0 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20 6f  onsidered part o
22af0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
22b00 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  ble interface,.*
22b10 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65 72  * which is exper
22b20 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a  imental and subj
22b30 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
22b40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
22b50 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
22b60 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
22b70 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
22b80 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
22b90 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
22ba0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
22bb0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
22bc0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
22bd0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
22be0 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
22bf0 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
22c00 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
22c10 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
22c20 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
22c30 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
22c40 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
22c50 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
22c60 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
22c70 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
22c80 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
22c90 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
22ca0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
22cb0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
22cc0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
22cd0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
22ce0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
22cf0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
22d00 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
22d10 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
22d20 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
22d30 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
22d40 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
22d50 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
22d60 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
22d70 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
22d80 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
22d90 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
22da0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
22db0 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  OB.**.** An inst
22dc0 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  ance of the foll
22dd0 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74 72  owing opaque str
22de0 75 63 74 75 72 65 20 69 73 20 75 73 65 64 20 74  ucture is used t
22df0 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 20  o .** represent 
22e00 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20  an blob-handle. 
22e10 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20 69   A blob-handle i
22e20 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a 20  s created by.** 
22e30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
22e40 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72 6f  en()] and destro
22e50 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
22e60 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
22e70 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
22e80 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
22e90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
22ea0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
22eb0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
22ec0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
22ed0 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
22ee0 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e  ons of the blob.
22ef0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
22f00 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
22f10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22f20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
22f30 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 65  .** blob in byte
22f40 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
22f50 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
22f60 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
22f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22f80 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
22f90 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
22fa0 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68 61  .**.** Open a ha
22fb0 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62  ndle to the blob
22fc0 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f 77 20   located in row 
22fd0 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a 43  iRow,, column zC
22fe0 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c 65  olumn, .** table
22ff0 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
23000 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74 68  ase zDb. i.e. th
23010 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 74  e same blob that
23020 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65 6c   would.** be sel
23030 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
23040 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
23050 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
23060 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
23070 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a  E rowid = iRow;.
23080 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  ** </pre>.**.** 
23090 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
230a0 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
230b0 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
230c0 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72  opened for .** r
230d0 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63  ead and write ac
230e0 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
230f0 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73  ero, the blob is
23100 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
23110 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a   .** access..**.
23120 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
23130 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
23140 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e  turned and the n
23150 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ew .** [sqlite3_
23160 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64  blob | blob hand
23170 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74  le] is written t
23180 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f 74  o *ppBlob..** Ot
23190 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
231a0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
231b0 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
231c0 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
231d0 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
231e0 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
231f0 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73   caller..** This
23200 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
23210 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
23220 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
23230 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
23240 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
23250 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
23260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
23270 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
23280 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
23290 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
232a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
232b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
232c0 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
232d0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
232e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
232f0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
23300 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
23310 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
23320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c  ** CAPI3REF:  Cl
23330 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
23340 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e  e.**.** Close an
23350 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
23360 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
23370 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
23380 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
23390 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
233a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
233b0 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
233c0 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
233d0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
233e0 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
233f0 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65  of the blob acce
23400 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f  ssible via the o
23410 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
23420 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
23430 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61  dle] passed as a
23440 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69  n argument..*/.i
23450 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
23460 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
23470 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
23480 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61  PI3REF:  Read Da
23490 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
234a0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
234b0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
234c0 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64   is used to read
234d0 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70   data from an op
234e0 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
234f0 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
23500 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65  le] into a calle
23510 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r supplied buffe
23520 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66  r..** n bytes of
23530 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
23540 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20   into buffer.** 
23550 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20  z from the open 
23560 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61  blob, starting a
23570 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
23580 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
23590 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
235a0 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72   returned. Other
235b0 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51  wise, an .** [SQ
235c0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c  LITE_ERROR | SQL
235d0 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ite error code] 
235e0 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
235f0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
23600 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
23610 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
23620 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
23630 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
23640 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a  _blob *, void *z
23650 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
23660 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
23670 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44  PI3REF:  Write D
23680 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20  ata Into A BLOB 
23690 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a  Incrementally.**
236a0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
236b0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
236c0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
236d0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
236e0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
236f0 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65  ndle] from a use
23700 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r supplied buffe
23710 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66  r..** n bytes of
23720 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
23730 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
23740 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
23750 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  y z into the ope
23760 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67  n blob, starting
23770 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
23780 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
23790 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
237a0 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
237b0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
237c0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61  t argument.** wa
237d0 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72  s not opened for
237e0 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
237f0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23800 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
23810 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a  pen()].*** was z
23820 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74  ero), this funct
23830 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
23840 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
23850 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
23860 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
23870 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
23880 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 74 20  of the blob, it 
23890 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
238a0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
238b0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
238c0 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  b using this API
238d0 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20 69  . If.** offset i
238e0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
238f0 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d  han n bytes from
23900 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
23910 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  blob, .** [SQLIT
23920 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
23930 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
23940 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a   is written..**.
23950 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
23960 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
23970 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
23980 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
23990 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
239a0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
239b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
239c0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
239d0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
239e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
239f0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
23a00 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
23a10 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
23a20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
23a30 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
23a40 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 74 75  CAPI3REF:  Virtu
23a50 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
23a60 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76  bjects.**.** A v
23a70 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65  irtual filesyste
23a80 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73  m (VFS) is an [s
23a90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
23aa0 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ct.** that SQLit
23ab0 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61  e uses to intera
23ac0 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75  ct.** with the u
23ad0 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
23ae0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73  ing system.  Mos
23af0 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  t builds come wi
23b00 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
23b10 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
23b20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
23b30 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
23b40 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
23b50 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
23b60 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
23b70 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
23b80 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
23b90 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
23ba0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
23bb0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  vided..**.** The
23bc0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e   sqlite3_vfs_fin
23bd0 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  d() interface re
23be0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23bf0 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69  to a VFS given i
23c00 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20 4e 61 6d  ts.** name.  Nam
23c10 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73  es are case sens
23c20 69 74 69 76 65 2e 20 20 49 66 20 74 68 65 72 65  itive.  If there
23c30 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20   is no match, a 
23c40 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
23c50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
23c60 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
23c70 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
23c80 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  lt .** VFS is re
23c90 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65  turned..**.** Ne
23ca0 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
23cb0 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
23cc0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
23cd0 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20 6e 65 77  ().  Each.** new
23ce0 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
23cf0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
23d00 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
23d10 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65  g is set..** The
23d20 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
23d30 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
23d40 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
23d50 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f  ut injury..** To
23d60 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
23d70 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
23d80 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
23d90 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
23da0 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
23db0 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
23dc0 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
23dd0 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
23de0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
23df0 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
23e00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
23e10 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
23e20 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
23e30 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
23e40 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
23e50 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
23e60 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
23e70 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
23e80 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 74  .** .** Unregist
23e90 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
23ea0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
23eb0 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
23ec0 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20  face..** If the 
23ed0 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
23ee0 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
23ef0 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
23f00 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
23f10 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
23f20 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
23f30 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  S is arbitrary..
23f40 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  */.sqlite3_vfs *
23f50 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
23f60 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66  (const char *zVf
23f70 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69  sName);.int sqli
23f80 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
23f90 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
23fa0 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e  nt makeDflt);.in
23fb0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  t sqlite3_vfs_un
23fc0 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
23fd0 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _vfs*);../*.** C
23fe0 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73  API3REF: Mutexes
23ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
24000 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
24010 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74  e routines for t
24020 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f  hread.** synchro
24030 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67  nization.  Thoug
24040 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e  h they are inten
24050 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ded for internal
24060 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
24070 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e  e, code that lin
24080 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
24090 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65  e is.** permitte
240a0 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20  d to use any of 
240b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
240c0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
240d0 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
240e0 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69  tains multiple i
240f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a  mplementations .
24100 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
24110 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
24120 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
24130 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
24140 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
24150 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
24160 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f  le-time.  The fo
24170 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65  llowing.** imple
24180 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61  mentations are a
24190 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
241a0 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a  SQLite core:.**.
241b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
241c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f    SQLITE_MUTEX_O
241d0 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  S2.** <li>   SQL
241e0 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
241f0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  D.** <li>   SQLI
24200 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20  TE_MUTEX_W32.** 
24210 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
24220 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c  TEX_NOOP.** </ul
24230 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
24240 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d  TE_MUTEX_NOOP im
24250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
24260 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65  a set of routine
24270 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  s .** that does 
24280 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20  no real locking 
24290 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61  and is appropria
242a0 74 65 20 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a  te for use in .*
242b0 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  * a single-threa
242c0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  ded application.
242d0 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54    The SQLITE_MUT
242e0 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54  EX_OS2,.** SQLIT
242f0 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c  E_MUTEX_PTHREAD,
24300 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
24310 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61  X_W32 implementa
24320 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70  tions.** are app
24330 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
24340 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78 2c 20   on os/2, unix, 
24350 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a 2a 20  and windows..** 
24360 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73  .** If SQLite is
24370 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
24380 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
24390 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73  APPDEF preproces
243a0 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66  sor.** macro def
243b0 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51  ined (with "-DSQ
243c0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
243d0 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d  F=1"), then no m
243e0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
243f0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64  tation is includ
24400 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
24410 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74  ary.  The.** mut
24420 65 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  ex interface rou
24430 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
24440 72 65 20 62 65 63 6f 6d 65 20 65 78 74 65 72 6e  re become extern
24450 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63 65 73  al.** references
24460 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 6c   in the SQLite l
24470 69 62 72 61 72 79 20 66 6f 72 20 77 68 69 63 68  ibrary for which
24480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
24490 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72 6f 76  .** must be prov
244a0 69 64 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  ided by the appl
244b0 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 66  ication.  This f
244c0 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73 20 61  acility allows a
244d0 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
244e0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
244f0 6e 73 74 20 53 51 4c 69 74 65 20 74 6f 20 70 72  nst SQLite to pr
24500 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 6d 75  ovide its own mu
24510 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
24520 61 74 69 6f 6e 20 77 69 74 68 6f 75 74 20 68 61  ation without ha
24530 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79 20 74  ving to modify t
24540 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a  he SQLite core..
24550 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24560 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
24570 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65  routine allocate
24580 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78  s a new.** mutex
24590 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
245a0 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 20 49  ointer to it.  I
245b0 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
245c0 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
245d0 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
245e0 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
245f0 74 65 64 2e 20 20 53 51 4c 69 74 65 0a 2a 2a 20  ted.  SQLite.** 
24600 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20  will unwind its 
24610 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e  stack and return
24620 20 61 6e 20 65 72 72 6f 72 2e 20 20 54 68 65 20   an error.  The 
24630 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
24640 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
24650 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
24660 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
24670 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
24680 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
24690 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
246a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
246b0 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
246c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
246d0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
246e0 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
246f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
24700 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
24710 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
24720 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
24730 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
24740 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
24750 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24760 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f 75 6c 3e  TIC_LRU.** </ul>
24770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
24780 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
24790 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
247a0 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
247b0 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
247c0 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
247d0 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
247e0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
247f0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
24800 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
24810 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
24820 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
24830 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a  _FAST is used..*
24840 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
24850 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
24860 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
24870 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
24880 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
24890 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
248a0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
248b0 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
248c0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
248d0 2e 20 20 42 75 74 20 53 51 4c 69 74 65 20 77 69  .  But SQLite wi
248e0 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
248f0 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
24900 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
24910 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
24920 65 64 73 20 6f 6e 65 2e 20 20 49 66 20 61 20 66  eds one.  If a f
24930 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
24940 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
24950 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
24960 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
24970 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
24980 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
24990 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
249a0 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
249b0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
249c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
249d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 74 68 65  ..**.** The othe
249e0 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65  r allowed parame
249f0 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  ters to sqlite3_
24a00 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61  mutex_alloc() ea
24a10 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70  ch return.** a p
24a20 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74  ointer to a stat
24a30 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d  ic preexisting m
24a40 75 74 65 78 2e 20 20 46 6f 75 72 20 73 74 61 74  utex.  Four stat
24a50 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a  ic mutexes are.*
24a60 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75  * used by the cu
24a70 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66  rrent version of
24a80 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65   SQLite.  Future
24a90 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24aa0 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61  ite.** may add a
24ab0 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63  dditional static
24ac0 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69   mutexes.  Stati
24ad0 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f  c mutexes are fo
24ae0 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73  r internal.** us
24af0 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79  e by SQLite only
24b00 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
24b10 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20  that use SQLite 
24b20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a  mutexes should.*
24b30 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64  * use only the d
24b40 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72  ynamic mutexes r
24b50 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54  eturned by SQLIT
24b60 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a  E_MUTEX_FAST or.
24b70 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
24b80 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a  RECURSIVE..**.**
24b90 20 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e   Note that if on
24ba0 65 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63  e of the dynamic
24bb0 20 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72   mutex parameter
24bc0 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
24bd0 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54  FAST.** or SQLIT
24be0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
24bf0 45 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20  E) is used then 
24c00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
24c10 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  loc().** returns
24c20 20 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74   a different mut
24c30 65 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c  ex on every call
24c40 2e 20 20 42 75 74 20 66 6f 72 20 74 68 65 20 73  .  But for the s
24c50 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78 20  tatic .** mutex 
24c60 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
24c70 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
24c80 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
24c90 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
24ca0 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
24cb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24cc0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
24cd0 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63   routine dealloc
24ce0 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c  ates a previousl
24cf0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64  y.** allocated d
24d00 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 53  ynamic mutex.  S
24d10 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
24d20 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
24d30 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
24d40 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
24d50 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64 79  locates.  The dy
24d60 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
24d70 73 74 20 6e 6f 74 20 62 65 20 69 6e 20 0a 2a 2a  st not be in .**
24d80 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61   use when they a
24d90 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20  re deallocated. 
24da0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
24db0 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
24dc0 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
24dd0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
24de0 20 62 65 68 61 76 69 6f 72 2e 20 20 53 51 4c 69   behavior.  SQLi
24df0 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
24e00 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
24e10 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 54 68   mutex..**.** Th
24e20 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
24e30 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69  enter() and sqli
24e40 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
24e50 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
24e60 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d  .** to enter a m
24e70 75 74 65 78 2e 20 20 49 66 20 61 6e 6f 74 68 65  utex.  If anothe
24e80 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65  r thread is alre
24e90 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d  ady within the m
24ea0 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  utex,.** sqlite3
24eb0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77  _mutex_enter() w
24ec0 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71  ill block and sq
24ed0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
24ee0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
24ef0 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54   SQLITE_BUSY.  T
24f00 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
24f10 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  _try() interface
24f20 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
24f30 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  OK.** upon succe
24f40 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 4d 75  ssful entry.  Mu
24f50 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73  texes created us
24f60 69 6e 67 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ing SQLITE_MUTEX
24f70 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 0a 2a  _RECURSIVE can.*
24f80 2a 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c  * be entered mul
24f90 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74  tiple times by t
24fa0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20  he same thread. 
24fb0 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74   In such cases t
24fc0 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73  he,.** mutex mus
24fd0 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65  t be exited an e
24fe0 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74  qual number of t
24ff0 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74  imes before anot
25000 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61  her thread.** ca
25010 6e 20 65 6e 74 65 72 2e 20 20 49 66 20 74 68 65  n enter.  If the
25020 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69   same thread tri
25030 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20  es to enter any 
25040 6f 74 68 65 72 20 6b 69 6e 64 20 6f 66 20 6d 75  other kind of mu
25050 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 74 68 61 6e  tex.** more than
25060 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76   once, the behav
25070 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
25080 2e 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .   SQLite will 
25090 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a  never exhibit.**
250a0 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69   such behavior i
250b0 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66  n its own use of
250c0 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20   mutexes..**.** 
250d0 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 65 78  Some systems (ex
250e0 3a 20 77 69 6e 64 6f 77 73 39 35 29 20 64 6f 20  : windows95) do 
250f0 6e 6f 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  not the operatio
25100 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  n implemented by
25110 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
25120 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f  x_try().  On tho
25130 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69  se systems, sqli
25140 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
25150 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79 73 20 72  will.** always r
25160 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53  eturn SQLITE_BUS
25170 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  Y.  The SQLite c
25180 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73  ore only ever us
25190 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  es.** sqlite3_mu
251a0 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20  tex_try() as an 
251b0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20  optimization so 
251c0 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62  this is acceptab
251d0 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
251e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
251f0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
25200 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
25210 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
25220 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
25230 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
25240 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61 76  read.  The behav
25250 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
25260 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
25270 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
25280 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
25290 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
252a0 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
252b0 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
252c0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
252d0 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
252e0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
252f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
25300 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
25310 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
25320 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
25330 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
25340 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
25350 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
25360 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
25370 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
25380 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
25390 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
253a0 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
253b0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
253c0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
253d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
253e0 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
253f0 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
25400 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
25410 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f 75 74  Verifcation Rout
25420 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ines.**.** The s
25430 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
25440 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
25450 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
25460 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
25470 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
25480 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
25490 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
254a0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a  e SQLite core.**
254b0 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73   never uses thes
254c0 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70  e routines excep
254d0 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65  t inside an asse
254e0 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61  rt() and applica
254f0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76  tions.** are adv
25500 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74  ised to follow t
25510 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63  he lead of the c
25520 6f 72 65 2e 20 20 54 68 65 20 63 6f 72 65 20 6f  ore.  The core o
25530 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  nly.** provides 
25540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
25550 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
25560 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  es when it is co
25570 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74  mpiled.** with t
25580 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he SQLITE_DEBUG 
25590 66 6c 61 67 2e 20 20 45 78 74 65 72 6e 61 6c 20  flag.  External 
255a0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
255b0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
255c0 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
255d0 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
255e0 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
255f0 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
25600 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
25610 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
25620 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25630 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74  tines should ret
25640 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
25650 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61  mutex in their a
25660 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65  rgument.** is he
25670 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20  ld or not held, 
25680 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79  respectively, by
25690 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
256a0 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ead..**.** The i
256b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
256c0 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
256d0 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
256e0 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
256f0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
25700 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49  ually work..** I
25710 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
25720 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
25730 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
25740 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
25750 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
25760 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20  should at least 
25770 70 72 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a  provide stubs.**
25780 20 74 68 61 74 20 61 6c 77 61 79 73 20 72 65 74   that always ret
25790 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74  urn true so that
257a0 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65   one does not ge
257b0 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73  t spurious.** as
257c0 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
257d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61  ..**.** If the a
257e0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
257f0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
25800 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
25810 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f  r then.** the ro
25820 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
25830 75 72 6e 20 31 2e 20 20 54 68 69 73 20 73 65 65  urn 1.  This see
25840 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
25850 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
25860 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
25870 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
25880 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
25890 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
258a0 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
258b0 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
258c0 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
258d0 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
258e0 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
258f0 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
25900 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
25910 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
25920 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
25930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
25940 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
25950 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
25960 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
25970 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
25980 64 6f 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  do.  The sqlite3
25990 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
259a0 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73   .** interface s
259b0 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
259c0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
259d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
259e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  /.int sqlite3_mu
259f0 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
25a00 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
25a10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
25a20 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
25a30 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
25a40 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65  3REF: Mutex Type
25a50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
25a60 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
25a70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61  ()] interface ta
25a80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
25a90 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69  ument.** which i
25aa0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
25ab0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
25ac0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
25ad0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20  ITE_MUTEX_FAST  
25ae0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
25af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
25b00 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  X_RECURSIVE     
25b10 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
25b20 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
25b30 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65  _MASTER    2.#de
25b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
25b50 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20  X_STATIC_MEM    
25b60 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33     3  /* sqlite3
25b70 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65  _malloc() */.#de
25b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
25b90 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20  X_STATIC_MEM2   
25ba0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
25bb0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
25bc0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
25bd0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
25be0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
25bf0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
25c00 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
25c10 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
25c20 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
25c30 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
25c40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
25c50 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
25c60 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
25c70 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Files.**.** The
25c80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
25c90 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
25ca0 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65  ace makes a dire
25cb0 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a  ct call to the.*
25cc0 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  * xFileControl m
25cd0 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73  ethod for the [s
25ce0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
25cf0 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  s] object associ
25d00 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70  ated.** with a p
25d10 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
25d20 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  se identified by
25d30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
25d40 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 6e 61  ment.  The.** na
25d50 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
25d60 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61  se is the name a
25d70 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64  ssigned to the d
25d80 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a  atabase by the.*
25d90 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  * <a href="lang_
25da0 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54  attach.html">ATT
25db0 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d  ACH</a> SQL comm
25dc0 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20  and that opened 
25dd0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
25de0 20 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65    To control the
25df0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
25e00 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d  ile, use the nam
25e10 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61  e "main".** or a
25e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
25e30 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
25e40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
25e50 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
25e60 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
25e70 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
25e80 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
25e90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25ea0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
25eb0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
25ec0 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
25ed0 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 43  ue of the xFileC
25ee0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64  ontrol.** method
25ef0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 74   becomes the ret
25f00 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
25f10 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
25f20 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
25f30 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
25f40 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
25f50 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
25f60 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
25f70 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
25f80 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
25f90 74 75 72 6e 65 64 2e 20 20 54 68 69 73 20 65 72  turned.  This er
25fa0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e  ror.** code is n
25fb0 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 61 6e  ot remembered an
25fc0 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65  d will not be re
25fd0 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c 69 74  called by [sqlit
25fe0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a  e3_errcode()].**
25ff0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
26000 6d 73 67 28 29 5d 2e 20 20 54 68 65 20 75 6e 64  msg()].  The und
26010 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
26020 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
26030 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
26040 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
26050 54 68 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20  There is no way 
26060 74 6f 20 64 69 73 74 69 6e 67 75 69 73 68 20 62  to distinguish b
26070 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63  etween.** an inc
26080 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61  orrect zDbName a
26090 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  nd an SQLITE_ERR
260a0 4f 52 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74  OR return from t
260b0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
260c0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
260d0 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  thod..**.** See 
260e0 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
260f0 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
26100 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
26110 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
26120 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
26130 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
26140 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
26150 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74   Undo the hack t
26160 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f  hat converts flo
26170 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65  ating point type
26180 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72  s to integer for
26190 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72  .** builds on pr
261a0 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74  ocessors without
261b0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
261c0 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64  support..*/.#ifd
261d0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
261e0 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
261f0 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e  undef double.#en
26200 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70  dif..#ifdef __cp
26210 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e  lusplus.}  /* En
26220 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e  d of the 'extern
26230 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23   "C"' block */.#
26240 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a           endif.#endif.