/ Hex Artifact Content
Login

Artifact 4340f2063848977e9eefd534ee13776f5cc9b0f0:


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 34 38 20 32 30 30 37 2f  in,v 1.248 2007/
05f0: 30 38 2f 33 30 20 31 34 3a 31 30 3a 33 30 20 64  08/30 14:10:30 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 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10a0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
10b0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
10c0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
10d0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
10e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
10f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a  nstance of the.*
1100: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  * opaque structu
1110: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
1120: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
1130: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
1140: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
1150: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
1160: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
1170: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1180: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
11a0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
11b0: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
11c0: 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b  ructors.** and [
11d0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
11e0: 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74   is its destruct
11f0: 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  or.  There are m
1200: 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66  any other interf
1210: 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73  aces.** (such as
1220: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1230: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
1240: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1250: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
1260: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1270: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
1280: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
1290: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69  e methods on thi
12a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  s.** object..*/.
12b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
12c0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
12d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12e0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
12f0: 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f 6d   Types.**.** Som
1300: 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20 6e  e compilers do n
1310: 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 20 22  ot support the "
1320: 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61 74  long long" datat
1330: 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61 76 65  ype.  So we have
1340: 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69 6c  .** to do compil
1350: 65 72 2d 73 70 65 63 69 66 69 63 20 74 79 70 65  er-specific type
1360: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
1370: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
1380: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
1390: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
13a0: 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
13b0: 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20 36 34  ons require a 64
13c0: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61 72 67  -bit integer arg
13d0: 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73 65  uments..** Those
13e0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
13f0: 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67 20 74  declared using t
1400: 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f 0a  his typedef..*/.
1410: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
1420: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
1430: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1440: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
1450: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1460: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
1470: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
1480: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
1490: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
14a0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
14b0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
14c0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
14d0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
14e0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
14f0: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1500: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
1510: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
1520: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
1530: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
1540: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
1550: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1560: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
1570: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1580: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
1590: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
15a0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
15b0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
15c0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
15d0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
15e0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
15f0: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
1600: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
1610: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a  floating-point.*
1620: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1630: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
1640: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
1650: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
1660: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
1670: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
1680: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
1690: 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61  nection.**.** Ca
16a0: 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ll this function
16b0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
16c0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
16d0: 68 61 74 20 77 61 73 20 70 72 65 76 69 6f 75 73  hat was previous
16e0: 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  ly.** returned f
16f0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
1700: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1710: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
1720: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1730: 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f 72 72  ()] and the corr
1740: 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61  esponding databa
1750: 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63 6c  se will by.** cl
1760: 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20  osed..**.** All 
1770: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
1780: 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 5b 73  repared using [s
1790: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17a0: 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
17b0: 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
17c0: 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65 73 74  ()] must be dest
17d0: 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  royed using [sql
17e0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
17f0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
1800: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
1810: 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 53 51  d. Otherwise, SQ
1820: 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 65 74  LITE_BUSY is ret
1830: 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a  urned and the.**
1840: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1850: 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70 65  tion remains ope
1860: 6e 2e 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 6e 67  n..**.** Passing
1870: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 20   this routine a 
1880: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1890: 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61 6c 72  ion that has alr
18a0: 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c 6f  eady been.** clo
18b0: 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e 20 75  sed results in u
18c0: 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
18d0: 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69 6e 74  r.  If other int
18e0: 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a 2a 20  erfaces that.** 
18f0: 72 65 66 65 72 65 6e 63 65 20 74 68 65 20 73 61  reference the sa
1900: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1910: 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e 64 69  ection are pendi
1920: 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 74 68  ng (either in th
1930: 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65 61 64  e.** same thread
1940: 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65 6e 74   or in different
1950: 20 74 68 72 65 61 64 73 29 20 77 68 65 6e 20 74   threads) when t
1960: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
1970: 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20 74  alled,.** then t
1980: 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1990: 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 73 20  ndefined and is 
19a0: 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c 79  almost certainly
19b0: 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
19c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
19d0: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
19e0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
19f0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
1a00: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
1a10: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
1a20: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
1a30: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
1a40: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
1a50: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
1a60: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
1a70: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
1a80: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
1a90: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
1aa0: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
1ab0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ac0: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
1ad0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
1ae0: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  ce.**.** This in
1af0: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1b00: 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d 65  to do a one-time
1b10: 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f 66   evaluatation of
1b20: 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65   zero.** or more
1b30: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1b40: 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f 66 20    UTF-8 text of 
1b50: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1b60: 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61 6c  ts to.** be eval
1b70: 75 74 65 64 20 69 73 20 70 61 73 73 65 64 20 69  uted is passed i
1b80: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  n as the second 
1b90: 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1ba0: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72  statements.** ar
1bb0: 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 20 62  e prepared one b
1bc0: 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71 6c  y one using [sql
1bd0: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c  ite3_prepare()],
1be0: 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75 73   evaluated.** us
1bf0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1c00: 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73 74 72  p()], then destr
1c10: 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  oyed using [sqli
1c20: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1c30: 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f 72  .**.** If one or
1c40: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c   more of the SQL
1c50: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1c60: 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a 2a  queries, then.**
1c70: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
1c80: 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  nction specified
1c90: 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
1ca0: 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76 6f  meter is.** invo
1cb0: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
1cc0: 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65  h row of the que
1cd0: 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 69 73  ry result.  This
1ce0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f   callback.** sho
1cf0: 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74  uld normally ret
1d00: 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63  urn 0.  If the c
1d10: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d20: 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61  a non-zero.** va
1d30: 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71 75 65  lue then the que
1d40: 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c 20 61  ry is aborted, a
1d50: 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ll subsequent SQ
1d60: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1d70: 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e 64 20  are skipped and 
1d80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
1d90: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1da0: 72 6e 73 20 74 68 65 20 53 51 4c 49 54 45 5f 41  rns the SQLITE_A
1db0: 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BORT..**.** The 
1dc0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
1dd0: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1de0: 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
1df0: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 0a  pointer that is.
1e00: 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
1e10: 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
1e20: 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 69 74  k function as it
1e30: 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
1e40: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 6e 64  r..**.** The 2nd
1e50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e60: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1e70: 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ion is the numbe
1e80: 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  r of.** columns 
1e90: 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 65 73  in the query res
1ea0: 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 70 61  ult.  The 3rd pa
1eb0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1ec0: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 61 6e  allback.** is an
1ed0: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67   array of string
1ee0: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61  s holding the va
1ef0: 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f  lues for each co
1f00: 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72 61  lumn.** as extra
1f10: 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  cted using [sqli
1f20: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1f30: 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  )]..** The 4th p
1f40: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f50: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
1f60: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73 0a  rray of strings.
1f70: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e  ** obtained usin
1f80: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  g [sqlite3_colum
1f90: 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 68 6f  n_name()] and ho
1fa0: 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e 61 6d  lding.** the nam
1fb0: 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  es of each colum
1fc0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  n..**.** The cal
1fd0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
1fe0: 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65 6e  ay be NULL, even
1ff0: 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20 20 41   for queries.  A
2000: 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63   NULL.** callbac
2010: 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f  k is not an erro
2020: 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65 61 6e  r.  It just mean
2030: 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62 61  s that no callba
2040: 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e  ck.** will be in
2050: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  voked..**.** If 
2060: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2070: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
2080: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
2090: 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f 74 20  SQL (but.** not 
20a0: 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e 67 20  while executing 
20b0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20 74 68  the callback) th
20c0: 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  en an appropriat
20d0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
20e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
20f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2100: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2110: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 0a 2a  _malloc()] and.*
2120: 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64  * *errmsg is mad
2130: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2140: 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54 68 65  at message.  The
2150: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2160: 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e 73 69  n.** is responsi
2170: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
2180: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
2190: 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f 72 0a  holds the error.
21a0: 2a 2a 20 6d 65 73 73 61 67 65 2e 20 20 20 55 73  ** message.   Us
21b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
21c0: 29 5d 20 66 6f 72 20 74 68 69 73 2e 20 20 49 66  )] for this.  If
21d0: 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c 0a 2a   errmsg==NULL,.*
21e0: 2a 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20  * then no error 
21f0: 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 72 20  message is ever 
2200: 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  written..**.** T
2210: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2220: 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20  is is SQLITE_OK 
2230: 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
2240: 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f  errors and.** so
2250: 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  me other [SQLITE
2260: 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  _OK | return cod
2270: 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 20 61  e] if there is a
2280: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68  n error.  .** Th
2290: 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 74  e particular ret
22a0: 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64  urn value depend
22b0: 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66  s on the type of
22c0: 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69   error. .**.*/.i
22d0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
22e0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
22f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2310: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
2320: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2330: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
2340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2350: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
2360: 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74  valuted */.  int
2370: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2380: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
2390: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
23a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
23b0: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
23c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23e0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
23f0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
2400: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
2410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2420: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
2430: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
2440: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
2450: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2460: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
2470: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  DS: SQLITE_OK.**
2480: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
2490: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
24a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
24b0: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
24c0: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62   set shown.** ab
24d0: 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ove in order to 
24e0: 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73  indicates succes
24f0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
2500: 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63  .** The result c
2510: 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 20 74  odes above are t
2520: 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74  he only ones ret
2530: 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2540: 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c  in its.** defaul
2550: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e  t configuration.
2560: 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b    However, the [
2570: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
2580: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
2590: 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75  .** API can be u
25a0: 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 61 74  sed to set a dat
25b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e  abase connectoin
25c0: 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20   to return more 
25d0: 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75  detailed.** resu
25e0: 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  lt codes..**.** 
25f0: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
2600: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
2610: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2620: 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66  odes].**.*/.#def
2630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
2640: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
2650: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
2660: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
2670: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
2680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2690: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
26a0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
26b0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
26c0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
26d0: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
26e0: 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53     2   /* NOT US
26f0: 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67  ED. Internal log
2700: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
2710: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
2720: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
2730: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
2740: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
2750: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2760: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
2770: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
2780: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
2790: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
27a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
27b0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
27c0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
27d0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
27e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27f0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
2800: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
2810: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
2820: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
2830: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
2840: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
2850: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
2860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2870: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
2880: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
2890: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
28a0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
28b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
28c0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
28d0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
28e0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
28f0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
2900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
2910: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
2920: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
2930: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
2940: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
2950: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
2960: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
2970: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
2980: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
2990: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29a0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
29b0: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
29c0: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
29d0: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
29e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
29f0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
2a00: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
2a10: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
2a20: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
2a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
2a40: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
2a50: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
2a60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2a70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2a80: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
2a90: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
2aa0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
2ab0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
2ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ad0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
2ae0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
2af0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
2b00: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
2b10: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
2b20: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2b30: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
2b40: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
2b50: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
2b60: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
2b70: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
2b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
2ba0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
2bb0: 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f  to contraint vio
2bc0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
2bd0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
2be0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
2bf0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
2c00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2c10: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
2c20: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
2c30: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
2c40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c50: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
2c60: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
2c70: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
2c80: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
2c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
2ca0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
2cb0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
2cc0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
2cd0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
2ce0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
2cf0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
2d00: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
2d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
2d20: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
2d30: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
2d40: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2d50: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
2d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d70: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
2d80: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
2d90: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
2da0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
2db0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
2dc0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
2dd0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2de0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
2df0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
2e00: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
2e10: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
2e20: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
2e30: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2e40: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
2e50: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
2e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e70: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
2e80: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  Codes.**.** In i
2e90: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
2ea0: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
2eb0: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
2ec0: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
2ed0: 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c 74  nteger.** result
2ee0: 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 65 64   codes described
2ef0: 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 65 73   at result-codes
2f00: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
2f10: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
2f20: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
2f30: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
2f40: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
2f50: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
2f60: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
2f70: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
2f80: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
2f90: 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20  oblems as users 
2fa0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
2fb0: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
2fc0: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
2fd0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
2fe0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
2ff0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
3000: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
3010: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
3020: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
3030: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
3040: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
3050: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
3060: 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 78 74  errors.  The ext
3070: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3080: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 28  es are enabled (
3090: 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 6f 72  or disabled) for
30a0: 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61   .** each databa
30b0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
30c0: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
30d0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
30e0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
30f0: 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66  ..** .** Some of
3100: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
3110: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3120: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
3130: 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78 70  above..** We exp
3140: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
3150: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
3160: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
3170: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
3180: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
3190: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
31a0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
31b0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
31c0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
31d0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
31e0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
31f0: 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  Lite..** .** The
3200: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
3210: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
3220: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
3230: 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 65 6c  s contains a rel
3240: 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79 20  ated.** primary 
3250: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
3260: 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d 61 72   prefix.  Primar
3270: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  y result codes c
3280: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 0a  ontain a single.
3290: 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  ** "_" character
32a0: 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 75  .  Extended resu
32b0: 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e  lt codes contain
32c0: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22   two or more "_"
32d0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
32e0: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
32f0: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
3300: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e   result code can
3310: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
3320: 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   its.** correspo
3330: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
3340: 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73  sult code by mas
3350: 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77  king off the low
3360: 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  er 8 bytes..**.*
3370: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
3380: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
3390: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
33a0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
33b0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
33c0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
33d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
33e0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53  READ          (S
33f0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
3400: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
3410: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
3420: 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45  _READ    (SQLITE
3430: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
3440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3450: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
3460: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3470: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
3480: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3490: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
34a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
34b0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
34c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
34d0: 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54  FSYNC     (SQLIT
34e0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
34f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3500: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
3510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3520: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
3530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3540: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
3550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3560: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
3570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
3580: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
3590: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
35a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
35b0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
35c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
35d0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
35e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
35f0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
3600: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3610: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
3620: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
3630: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51  LOCKED       (SQ
3640: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
3650: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
3660: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
3670: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
3680: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f 6d 62  tions.**.** Comb
3690: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66  ination of the f
36a0: 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 61 6c  ollowing bit val
36b0: 75 65 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ues are used as 
36c0: 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  the.** third arg
36d0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
36e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
36f0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
3700: 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 67 75  * as fourth argu
3710: 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f 70 65  ment to the xOpe
3720: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
3730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
3740: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f 0a 23   object..**.*/.#
3750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3760: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
3770: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
3780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3790: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
37a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
37b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
37c0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
37d0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
37e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
37f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
3800: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
3810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3820: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
3830: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
3840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3850: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
3860: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
3870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3880: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
3890: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
38a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
38b0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
38c0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
38d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
38e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
38f0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23      0x00000800.#
3900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3910: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
3920: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
3930: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
3940: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
3950: 4c 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a  L   0x00002000..
3960: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3970: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
3980: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
3990: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
39a0: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
39b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
39c0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
39d0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
39e0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
39f0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 66 6f  vector of the fo
3a00: 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 20 76  llowing.** bit v
3a10: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
3a20: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
3a30: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
3a40: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
3a50: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
3a60: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
3a70: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
3a80: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
3a90: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
3aa0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3ab0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3ac0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
3ad0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
3ae0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
3b00: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
3b10: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
3b20: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
3b30: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
3b40: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
3b50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
3b60: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
3b70: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
3b80: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
3b90: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
3ba0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
3bb0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
3bc0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
3bd0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
3be0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
3bf0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
3c00: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
3c10: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
3c20: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
3c30: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
3c40: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
3c50: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
3c60: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
3c70: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
3c80: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
3c90: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
3ca0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
3cb0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
3cc0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
3cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3ce0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
3cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
3d00: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
3d10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
3d20: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
3d30: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
3d40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
3d50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
3d60: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
3d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
3d80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
3d90: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
3da0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
3db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
3dc0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
3dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
3de0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
3df0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
3e00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
3e10: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
3e20: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
3e30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
3e40: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
3e50: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
3e60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
3e70: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
3e80: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
3e90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
3ea0: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
3eb0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
3ec0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
3ed0: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
3ee0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
3ef0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
3f00: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
3f10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
3f20: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
3f30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
3f40: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
3f50: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
3f60: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
3f70: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
3f80: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
3f90: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
3fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
3fb0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
3fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
3fd0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
3fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
3ff0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
4000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4010: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
4020: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
4030: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
4040: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
4050: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
4060: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
4070: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
4080: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
4090: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
40a0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
40b0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
40c0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
40d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
40e0: 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  ** object it use
40f0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
4100: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
4110: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
4120: 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  as.** the second
4130: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
4140: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
4150: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
4160: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
4170: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
4180: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
4190: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
41a0: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
41b0: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
41c0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
41d0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
41e0: 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  shed.  The SQLIT
41f0: 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 52 20 66  E_SYNC_BARRIER f
4200: 6c 61 67 0a 2a 2a 20 6d 65 61 6e 73 20 74 68 61  lag.** means tha
4210: 74 20 74 68 65 20 6e 6f 74 68 69 6e 67 20 61 63  t the nothing ac
4220: 74 75 61 6c 6c 79 20 6e 65 65 64 73 20 74 6f 20  tually needs to 
4230: 62 65 20 73 79 6e 63 68 65 64 20 74 6f 20 6d 61  be synched to ma
4240: 73 73 20 73 74 6f 72 61 67 65 2c 0a 2a 2a 20 62  ss storage,.** b
4250: 75 74 20 61 6c 6c 20 77 72 69 74 65 20 6f 70 65  ut all write ope
4260: 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 63 63  rations that occ
4270: 75 72 20 62 65 66 6f 72 65 20 74 68 65 20 62 61  ur before the ba
4280: 72 72 69 65 72 20 6d 75 73 74 20 63 6f 6d 70 6c  rrier must compl
4290: 65 74 65 0a 2a 2a 20 62 65 66 6f 72 65 20 61 6e  ete.** before an
42a0: 79 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  y write operatio
42b0: 6e 73 20 74 68 61 74 20 6f 63 63 75 72 20 61 66  ns that occur af
42c0: 74 65 72 20 74 68 65 20 62 61 72 72 69 65 72 20  ter the barrier 
42d0: 62 65 67 69 6e 2e 0a 2a 2a 20 54 68 65 20 53 51  begin..** The SQ
42e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
42f0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
4300: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
4310: 61 6e 74 69 63 73 2e 0a 2a 2a 20 54 68 65 20 53  antics..** The S
4320: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
4330: 66 6c 61 67 20 6d 65 61 6e 73 20 74 6f 20 75 73  flag means to us
4340: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
4350: 20 66 75 6c 6c 73 79 6e 63 0a 2a 2a 20 69 6e 73   fullsync.** ins
4360: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
4370: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4380: 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 52 20  TE_SYNC_BARRIER 
4390: 20 20 20 20 20 20 30 78 30 30 30 30 31 0a 23 64        0x00001.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
43b0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
43c0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
43d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
43e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
43f0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
4400: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
4410: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a      0x00010.../*
4420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4430: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
4440: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
4450: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
4460: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
4470: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
4480: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
4490: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
44a0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
44b0: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
44c0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
44d0: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
44e0: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
44f0: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
4500: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
4510: 20 6f 66 20 74 68 65 69 72 20 6f 77 6e 20 75 73   of their own us
4520: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
4530: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
4540: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
4550: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4560: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
4570: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
4580: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
4590: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
45a0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
45b0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
45c0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
45d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
45e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
45f0: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
4600: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
4610: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
4620: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
4630: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
4640: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
4650: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
4660: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
4670: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
4680: 0a 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e 20 66  .** Every open f
4690: 69 6c 65 20 69 6e 20 74 68 65 20 5b 73 71 6c 69  ile in the [sqli
46a0: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d  te3_vfs] xOpen m
46b0: 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20 61  ethod contains a
46c0: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
46d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
46e0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62 6a 65  e following obje
46f0: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
4700: 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20   defines the.** 
4710: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
4720: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
4730: 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e  operations again
4740: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
4750: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
4760: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
4770: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
4780: 66 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42 41  f SQLITE_SYNC_BA
4790: 52 52 49 45 52 2c 0a 2a 2a 20 53 51 4c 49 54 45  RRIER,.** SQLITE
47a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 53 51  _SYNC_NORMAL, SQ
47b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2e 20  LITE_SYNC_FULL. 
47c0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
47d0: 65 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  e means that.** 
47e0: 64 61 74 61 20 69 73 20 6e 6f 74 20 6e 65 63 65  data is not nece
47f0: 73 73 61 72 69 6c 79 20 73 79 6e 63 65 64 20 74  ssarily synced t
4800: 6f 20 64 69 73 6b 20 63 6f 6d 70 6c 65 74 65 6c  o disk completel
4810: 79 2c 20 6f 6e 6c 79 20 74 68 61 74 0a 2a 2a 20  y, only that.** 
4820: 61 6c 6c 20 77 72 69 74 65 73 20 74 68 61 74 20  all writes that 
4830: 6f 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 65  occur before the
4840: 20 73 79 6e 63 20 63 6f 6d 70 6c 65 74 65 20 62   sync complete b
4850: 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 77 72 69  efore any.** wri
4860: 74 65 73 20 74 68 61 74 20 6f 63 63 75 72 20 61  tes that occur a
4870: 66 74 65 72 20 74 68 65 20 73 79 6e 63 2e 20 20  fter the sync.  
4880: 54 68 65 20 73 65 63 6f 6e 64 20 66 6c 61 67 20  The second flag 
4890: 69 73 20 74 68 65 0a 2a 2a 20 6e 6f 72 6d 61 6c  is the.** normal
48a0: 20 66 73 79 6e 63 28 29 2e 20 20 54 68 65 20 74   fsync().  The t
48b0: 68 69 72 64 20 66 6c 61 67 20 69 73 20 61 20 4f  hird flag is a O
48c0: 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S-X style fullsy
48d0: 6e 63 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  nc..** The SQLIT
48e0: 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61 67  E_SYNC_DATA flag
48f0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
4900: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
4910: 20 6f 6e 6c 79 0a 2a 2a 20 74 68 65 20 64 61 74   only.** the dat
4920: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61 6e  a of the file an
4930: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
4940: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
4950: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69  ed..** .** The i
4960: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
4970: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
4980: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
4990: 66 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  f.** SQLITE_LOCK
49a0: 5f 4e 4f 4e 45 2c 20 53 51 4c 49 54 45 5f 4c 4f  _NONE, SQLITE_LO
49b0: 43 4b 5f 52 45 41 44 2c 20 53 51 4c 49 54 45 5f  CK_READ, SQLITE_
49c0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 2c 0a 2a  LOCK_RESERVED,.*
49d0: 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  * SQLITE_LOCK_PE
49e0: 4e 44 49 4e 47 2c 20 6f 72 20 53 51 4c 49 54 45  NDING, or SQLITE
49f0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 2e  _LOCK_EXCLUSIVE.
4a00: 20 20 78 4c 6f 63 6b 28 29 0a 2a 2a 20 69 6e 63    xLock().** inc
4a10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
4a20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
4a30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ases the lock.  
4a40: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
4a50: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
4a60: 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20  hod looks.** to 
4a70: 73 65 65 20 69 66 20 61 6e 79 20 64 61 74 61 62  see if any datab
4a80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
4a90: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a 2a  either in this.*
4aa0: 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  * process or in 
4ab0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
4ac0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
4ad0: 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  n RESERVED,.** P
4ae0: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
4af0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
4b00: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
4b10: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
4b20: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
4b30: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e 6f   and false if no
4b40: 74 2e 0a 2a 2a 20 0a 2a 2a 20 78 42 72 65 61 6b  t..** .** xBreak
4b50: 4c 6f 63 6b 28 29 20 61 74 74 65 6d 70 74 73 20  Lock() attempts 
4b60: 74 6f 20 62 72 65 61 6b 20 61 20 6c 6f 63 6b 20  to break a lock 
4b70: 68 65 6c 64 20 62 79 20 61 6e 6f 74 68 65 72 20  held by another 
4b80: 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
4b90: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
4ba0: 72 65 6d 6f 76 65 20 61 20 73 74 61 6c 65 20 64  remove a stale d
4bb0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 2c 20 66 6f  ot-file lock, fo
4bc0: 72 20 65 78 61 6d 70 6c 65 2e 0a 2a 2a 20 49 74  r example..** It
4bd0: 20 72 65 74 75 72 6e 73 20 30 20 6f 6e 20 73 75   returns 0 on su
4be0: 63 63 65 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a 65  ccess and non-ze
4bf0: 72 6f 20 66 6f 72 20 61 20 66 61 69 6c 75 72 65  ro for a failure
4c00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
4c10: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
4c20: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
4c30: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
4c40: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
4c50: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
4c60: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
4c70: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
4c80: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
4c90: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
4ca0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
4cb0: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
4cc0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
4cd0: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
4ce0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
4cf0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
4d00: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
4d10: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
4d20: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
4d30: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
4d40: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
4d50: 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  i> SQLITE_IOCAP_
4d60: 41 54 4f 4d 49 43 0a 2a 2a 20 3c 6c 69 3e 20 53  ATOMIC.** <li> S
4d70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d80: 49 43 35 31 32 0a 2a 2a 20 3c 6c 69 3e 20 53 51  IC512.** <li> SQ
4d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4da0: 43 31 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  C1K.** <li> SQLI
4db0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
4dc0: 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45  K.** <li> SQLITE
4dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 0a  _IOCAP_ATOMIC4K.
4de0: 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49  ** <li> SQLITE_I
4df0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 0a 2a 2a  OCAP_ATOMIC8K.**
4e00: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4e10: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 0a 2a 2a 20  AP_ATOMIC16K.** 
4e20: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e30: 50 5f 41 54 4f 4d 49 43 33 32 4b 0a 2a 2a 20 3c  P_ATOMIC32K.** <
4e40: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4e50: 5f 41 54 4f 4d 49 43 36 34 4b 0a 2a 2a 20 3c 6c  _ATOMIC64K.** <l
4e60: 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  i> SQLITE_IOCAP_
4e70: 53 41 46 45 5f 41 50 50 45 4e 44 0a 2a 2a 20 3c  SAFE_APPEND.** <
4e80: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4e90: 5f 53 45 51 55 45 4e 54 49 41 4c 0a 2a 2a 20 3c  _SEQUENTIAL.** <
4ea0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
4eb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4ec0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
4ed0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
4ee0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
4ef0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
4f00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
4f10: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
4f20: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
4f30: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
4f40: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
4f50: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
4f60: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
4f70: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
4f80: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
4f90: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
4fa0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
4fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
4fc0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
4fd0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
4fe0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
4ff0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
5000: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
5010: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
5020: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
5030: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
5040: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
5050: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
5060: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
5070: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5080: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5090: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
50a0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
50b0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
50c0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
50d0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
50e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
50f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5100: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
5110: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
5120: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
5130: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
5140: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
5150: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
5160: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
5170: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
5180: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
5190: 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69 6e 74  iAmt, sqlite_int
51a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
51b0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
51c0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
51d0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
51e0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69 4f   sqlite_int64 iO
51f0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
5200: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
5210: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 69  _file*, sqlite_i
5220: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
5230: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
5240: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
5250: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
5260: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
5270: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 69  _file*, sqlite_i
5280: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
5290: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
52a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
52b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
52c0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
52d0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
52e0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
52f0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
5300: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 72 65  *);.  int (*xBre
5310: 61 6b 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  akLock)(sqlite3_
5320: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
5330: 78 4c 6f 63 6b 53 74 61 74 65 29 28 73 71 6c 69  xLockState)(sqli
5340: 74 65 33 5f 66 69 6c 65 20 2a 29 3b 0a 20 20 69  te3_file *);.  i
5350: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
5360: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
5370: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
5380: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
5390: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
53a0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
53b0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
53c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
53d0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
53e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
53f0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
5400: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
5410: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
5420: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
5430: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
5440: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
5450: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
5460: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
5470: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
5480: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
5490: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
54a0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
54b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
54c0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
54d0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
54e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
54f0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
5500: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
5510: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
5520: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
5530: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
5540: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5550: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
5560: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
5570: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
5580: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
5590: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
55a0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
55b0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
55c0: 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
55d0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
55e0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
55f0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
5600: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
5610: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
5620: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
5630: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
5640: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
5650: 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20 66  * The iVersion f
5660: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
5670: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
5680: 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72 65  arger for future
5690: 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
56a0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
56b0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
56c0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
56d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
56e0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
56f0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
5700: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
5710: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
5720: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
5730: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
5740: 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63 74  3_file.** struct
5750: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
5760: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
5770: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
5780: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
5790: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
57a0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
57b0: 73 74 65 72 65 64 20 76 66 73 20 6d 6f 64 75 6c  stered vfs modul
57c0: 65 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  es are kept on a
57d0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
57e0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
57f0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
5800: 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 67 69 73  e [sqlite3_regis
5810: 74 65 72 5f 76 66 73 28 29 5d 0a 2a 2a 20 61 6e  ter_vfs()].** an
5820: 64 20 5b 73 71 6c 69 74 65 33 5f 75 6e 72 65 67  d [sqlite3_unreg
5830: 69 73 74 65 72 5f 76 66 73 28 29 5d 20 69 6e 74  ister_vfs()] int
5840: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
5850: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
5860: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
5870: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
5880: 66 69 6e 64 5f 76 66 73 28 29 5d 20 69 6e 74 65  find_vfs()] inte
5890: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
58a0: 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  s the list..**.*
58b0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
58c0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
58d0: 65 6c 64 73 20 69 6e 20 74 68 65 20 73 71 6c 69  elds in the sqli
58e0: 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75  te3_vfs .** stru
58f0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
5900: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
5910: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
5920: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
5930: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
5940: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
5950: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
5960: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
5970: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
5980: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
5990: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
59a0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
59b0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
59c0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
59d0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
59e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
59f0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
5a00: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
5a10: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
5a20: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
5a30: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
5a40: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
5a50: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
5a60: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
5a70: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73   the zFilename s
5a80: 74 72 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a  tring passed to.
5a90: 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20  ** xOpen() is a 
5aa0: 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73  full pathname as
5ab0: 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 78 46   generated by xF
5ac0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e  ullPathname() an
5ad0: 64 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74  d.** that the st
5ae0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
5af0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
5b00: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
5b10: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 53  is.** called.  S
5b20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
5b30: 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72 65 20 61  ile] can store a
5b40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
5b50: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
5b60: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
5b70: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
5b80: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
5b90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
5ba0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
5bb0: 70 65 6e 28 29 20 69 73 20 61 20 63 6f 70 79 20  pen() is a copy 
5bc0: 6f 66 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  of the flags arg
5bd0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
5be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
5bf0: 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  If sqlite3_open(
5c00: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
5c10: 6e 31 36 28 29 0a 2a 2a 20 69 73 20 75 73 65 64  n16().** is used
5c20: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 73 20  , then flags is 
5c30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5c40: 57 52 49 54 45 20 7c 20 53 51 4c 49 54 45 5f 4f  WRITE | SQLITE_O
5c50: 50 45 4e 5f 43 52 45 41 54 45 2e 0a 2a 2a 20 49  PEN_CREATE..** I
5c60: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
5c70: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
5c80: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
5c90: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
5ca0: 6e 63 6c 75 64 65 20 53 51 4c 49 54 45 5f 4f 50  nclude SQLITE_OP
5cb0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 2e 20 20 4f 74  EN_READONLY.  Ot
5cc0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
5cd0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a  tFlags may be.**
5ce0: 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c   set..** .** SQL
5cf0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
5d00: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
5d10: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
5d20: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
5d30: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
5d40: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
5d50: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a  ng opened:.** .*
5d60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
5d70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
5d80: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
5d90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5da0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
5db0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
5dc0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
5dd0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
5de0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
5df0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
5e00: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
5e10: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
5e20: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5e30: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
5e40: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
5e50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
5e60: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
5e70: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
5e80: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 65 20  .** changes the 
5e90: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
5ea0: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
5eb0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
5ec0: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
5ed0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
5ee0: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
5ef0: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69   or rollback, mi
5f00: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
5f10: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
5f20: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
5f30: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
5f40: 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61  journal are.** a
5f50: 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e  lso a no-op.  An
5f60: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
5f70: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65  d the journal re
5f80: 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52  turn SQLITE_IOER
5f90: 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70  R..** Or the imp
5fa0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
5fb0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 65 20  t recognize the 
5fc0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
5fd0: 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67  will.** be doing
5fe0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
5ff0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
6000: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
6010: 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73  m order.** and s
6020: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
6030: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
6040: 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69  gly..** .** SQLi
6050: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
6060: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
6070: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
6080: 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74  the xOpen.** met
6090: 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  hod:.** .** <ul>
60a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
60c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
60d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
60e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
60f0: 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45   .** The [SQLITE
6100: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6110: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
6120: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
6130: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
6140: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
6150: 20 20 54 68 69 73 20 77 69 6c 6c 20 61 6c 77 61    This will alwa
6160: 79 73 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ys be set for TE
6170: 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  MP .** databases
6180: 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73 20 61 6e   and journals an
6190: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
61a0: 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
61b0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
61c0: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
61d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
61e0: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
61f0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
6200: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
6210: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
6220: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
6230: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
6240: 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a 20 53  e file..** .** S
6250: 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  pace to hold the
6260: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
6270: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
6280: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a  d as the third .
6290: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
62a0: 4f 70 65 6e 20 69 73 20 61 6c 6c 6f 63 61 74 65  Open is allocate
62b0: 64 20 62 79 20 63 61 6c 6c 65 72 20 28 74 68 65  d by caller (the
62c0: 20 53 51 4c 69 74 65 20 63 6f 72 65 29 2e 20 0a   SQLite core). .
62d0: 2a 2a 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  ** szOsFile byte
62e0: 73 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  s are allocated 
62f0: 66 6f 72 20 74 68 69 73 20 6f 62 6a 65 63 74 2e  for this object.
6300: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
6310: 6f 64 0a 2a 2a 20 66 69 6c 6c 73 20 69 6e 20 74  od.** fills in t
6320: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 70 61  he allocated spa
6330: 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66  ce..** .** The f
6340: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6350: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
6360: 65 20 30 20 28 74 6f 20 74 65 73 74 20 66 6f 72  e 0 (to test for
6370: 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61 6e 63   the.** existanc
6380: 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f 72 20  e of a file) or 
6390: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
63a0: 41 44 57 52 49 54 45 20 74 6f 20 74 65 73 74 20  ADWRITE to test 
63b0: 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 20 66  to see.** if a f
63c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
63d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
63e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
63f0: 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 74 65  EADONLY.** to te
6400: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
6410: 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  ile is read-only
6420: 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20  .  The file can 
6430: 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f  be a .** directo
6440: 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74  ry..** .** SQLit
6450: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
6460: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
6470: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
6480: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  e for.** the out
6490: 70 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20  put buffers for 
64a0: 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61 6e 64  xGetTempName and
64b0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 0a   xFullPathname..
64c0: 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ** .** The xRand
64d0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
64e0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
64f0: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
6500: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
6510: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
6520: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
6530: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
6540: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
6550: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
6560: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
6570: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
6580: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
6590: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
65a0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
65b0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
65c0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
65d0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
65e0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
65f0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
6600: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
6610: 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61 74 65  domness generate
6620: 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65  d.  The.** xSlee
6630: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
6640: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
6650: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
6660: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
6670: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
6680: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
6690: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
66a0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
66b0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
66c0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
66d0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
66e0: 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79  d.** time..*/.ty
66f0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6700: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
6710: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
6720: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
6730: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
6740: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
6750: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
6760: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
6770: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
6780: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
6790: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
67a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
67b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
67c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
67d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
67e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
67f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
6800: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
6810: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
6820: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
6830: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
6840: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
6850: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
6860: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
6870: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
6880: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
6890: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
68a0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
68b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
68c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
68d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
68f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
6900: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
6910: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
6920: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
6930: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
6940: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
6950: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
6960: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
6970: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
6980: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
6990: 2a 78 47 65 74 54 65 6d 70 4e 61 6d 65 29 28 73  *xGetTempName)(s
69a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 68 61  qlite3_vfs*, cha
69b0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
69c0: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
69d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
69e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
69f0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
6a00: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
6a10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
6a20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
6a30: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
6a40: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
6a50: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
6a60: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
6a70: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
6a80: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
6a90: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
6aa0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
6ab0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
6ac0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
6ad0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
6ae0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
6af0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
6b00: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
6b10: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
6b20: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
6b30: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
6b40: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
6b50: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
6b60: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
6b70: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
6b80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
6b90: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
6ba0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
6bb0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
6bc0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
6bd0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
6be0: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
6bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
6c00: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
6c10: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
6c20: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
6c30: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
6c40: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
6c50: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
6c60: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
6c70: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
6c80: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
6c90: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
6ca0: 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e 64 20  ine.** the kind 
6cb0: 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  of what kind of 
6cc0: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
6cd0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
6ce0: 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  s.** looking for
6cf0: 2e 20 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  .  With SQLITE_A
6d00: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
6d10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
6d20: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
6d30: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
6d40: 66 69 6c 65 20 65 78 69 73 74 73 2e 20 20 57 69  file exists.  Wi
6d50: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
6d60: 5f 52 45 41 44 57 52 49 54 45 2c 0a 2a 2a 20 74  _READWRITE,.** t
6d70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
6d80: 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  d checks to see 
6d90: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  if the file is b
6da0: 6f 74 68 20 72 65 61 64 61 62 6c 65 0a 2a 2a 20  oth readable.** 
6db0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20 57  and writable.  W
6dc0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
6dd0: 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65  S_READ the xAcce
6de0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
6df0: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
6e00: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
6e10: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
6e20: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
6e30: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
6e40: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
6e50: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
6e60: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
6e70: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
6e80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
6e90: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
6ea0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
6eb0: 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Codes.**.** This
6ec0: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
6ed0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
6ee0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
6ef0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
6f00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
6f10: 66 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64  feature..** By d
6f20: 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41  efault, SQLite A
6f30: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
6f40: 72 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32  rn one of only 2
6f50: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
6f60: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
6f70: 20 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65   codes].  When e
6f80: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
6f90: 6f 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  odes.** are enab
6fa0: 6c 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  led by this rout
6fb0: 69 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69  ine, the repetoi
6fc0: 72 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64  re of result cod
6fd0: 65 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63  es can be.** muc
6fe0: 68 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e  h larger and can
6ff0: 20 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f   (hopefully) pro
7000: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
7010: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
7020: 2a 20 61 62 6f 75 74 20 74 68 65 20 63 61 75 73  * about the caus
7030: 65 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  e of an error..*
7040: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
7050: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f  argument is a bo
7060: 6f 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74  olean value that
7070: 20 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20   turns extended 
7080: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
7090: 6f 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74  on and off.  Ext
70a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
70b0: 65 73 20 61 72 65 20 6f 66 66 20 62 79 20 64 65  es are off by de
70c0: 66 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63  fault for.** bac
70d0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
70e0: 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
70f0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
7100: 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
7110: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
7120: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
7130: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
7140: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7150: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
7160: 64 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  d.**.** Each ent
7170: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
7180: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
7190: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
71a0: 20 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20   integer key.** 
71b0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
71c0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
71d0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
71e0: 65 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  e as an undeclar
71f0: 65 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d  ed.** column nam
7200: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
7210: 72 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74  r _ROWID_.  If t
7220: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
7230: 6f 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65  olumn of.** type
7240: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
7250: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
7260: 6f 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72  olumn is another
7270: 20 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68   an alias for th
7280: 65 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a  e.** rowid..**.*
7290: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
72a0: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64  eturns the rowid
72b0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
72c0: 65 6e 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a  ent INSERT into.
72d0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
72e0: 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
72f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76  e connection giv
7300: 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  en in the first 
7310: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
7320: 66 20 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76  f no inserts hav
7330: 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
7340: 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65  on this database
7350: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  .** connection, 
7360: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
7370: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
7380: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
7390: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
73a0: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
73b0: 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20  the.** inserted 
73c0: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
73d0: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
73e0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
73f0: 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e  rigger.** is run
7400: 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20  ning.  But once 
7410: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
7420: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
7430: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
7440: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
7450: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
7460: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
7470: 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74   before the.** t
7480: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
7490: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
74a0: 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77  hread does a new
74b0: 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73   insert on the s
74c0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
74d0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
74e0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
74f0: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
7500: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
7510: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
7520: 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
7530: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
7540: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
7550: 65 66 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74  efined..*/.sqlit
7560: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
7570: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
7580: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
7590: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
75a0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
75b0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
75c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
75d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
75e0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
75f0: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
7600: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f  re changed.** (o
7610: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
7620: 6c 65 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f  leted) by the mo
7630: 73 74 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74  st recent SQL st
7640: 61 74 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a  atement.  Only.*
7650: 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  * changes that a
7660: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
7670: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
7680: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a  ERT, UPDATE, or.
7690: 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
76a0: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
76b0: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
76c0: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
76d0: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
76e0: 74 20 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20  t counted.  Use 
76f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
7700: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
7710: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e  nction.** to fin
7720: 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
7730: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
7740: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
7750: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
7760: 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e  rs..**.** Within
7770: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
7780: 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69  rigger, the sqli
7790: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
77a0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a  terface can be.*
77b0: 2a 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  * called to find
77c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
77d0: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
77e0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
77f0: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
7800: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
7810: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
7820: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
7830: 6f 66 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  of the trigger..
7840: 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65  **.** All change
7850: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65  s are counted, e
7860: 76 65 6e 20 69 66 20 74 68 65 79 20 77 65 72 65  ven if they were
7870: 20 6c 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79   later undone by
7880: 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f   a.** ROLLBACK o
7890: 72 20 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74  r ABORT.  Except
78a0: 2c 20 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69  , changes associ
78b0: 61 74 65 64 20 77 69 74 68 20 63 72 65 61 74 69  ated with creati
78c0: 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69  ng and.** droppi
78d0: 6e 67 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  ng tables are no
78e0: 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  t counted..**.**
78f0: 20 49 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69   If a callback i
7900: 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
7910: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
7920: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
7930: 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e  rsively,.** then
7940: 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20   the changes in 
7950: 74 68 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72  the inner, recur
7960: 73 69 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f  sive call are co
7970: 75 6e 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a  unted together.*
7980: 2a 20 77 69 74 68 20 74 68 65 20 63 68 61 6e 67  * with the chang
7990: 65 73 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20  es in the outer 
79a0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  call..**.** SQLi
79b0: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
79c0: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
79d0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
79e0: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
79f0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
7a00: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
7a10: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
7a20: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
7a30: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
7a40: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
7a50: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
7a60: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
7a70: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
7a80: 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20  ause of.** this 
7a90: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
7aa0: 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66  e change count f
7ab0: 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  or "DELETE FROM 
7ac0: 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a  table" will be.*
7ad0: 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73  * zero regardles
7ae0: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
7af0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
7b00: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
7b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65   in the.** table
7b20: 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75  . To get an accu
7b30: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
7b40: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
7b50: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
7b60: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
7b70: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
7b80: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tead..**.** If a
7b90: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d 61  nother thread ma
7ba0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
7bb0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
7bc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
7bd0: 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
7be0: 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  e is running the
7bf0: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
7c00: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
7c10: 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ne.** is undefin
7c20: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
7c30: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
7c40: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
7c50: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
7c60: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
7c70: 66 69 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  fied.***.** This
7c80: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
7c90: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
7ca0: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
7cb0: 61 74 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  at have been.** 
7cc0: 6d 6f 64 69 66 69 65 64 20 62 79 20 49 4e 53 45  modified by INSE
7cd0: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
7ce0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
7cf0: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
7d00: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
7d10: 20 6f 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e   opened. This in
7d20: 63 6c 75 64 65 73 20 55 50 44 41 54 45 2c 20 49  cludes UPDATE, I
7d30: 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45  NSERT and DELETE
7d40: 20 73 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63   statements exec
7d50: 75 74 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  uted.** as part 
7d60: 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
7d70: 61 6d 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73  ams. All changes
7d80: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
7d90: 73 6f 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73  soon as the.** s
7da0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
7db0: 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
7dc0: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
7dd0: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
7de0: 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f   is.** passed to
7df0: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
7e00: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
7e10: 69 6e 61 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a  inalise()])..**.
7e20: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
7e30: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28  [sqlite3_change(
7e40: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
7e50: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
7e60: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
7e70: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
7e80: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
7e90: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
7ea0: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
7eb0: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
7ec0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
7ed0: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
7ee0: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
7ef0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
7f00: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
7f10: 74 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c  ts form the tabl
7f20: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a  e.)  Because of.
7f30: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  ** this optimiza
7f40: 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65  tion, the change
7f50: 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45   count for "DELE
7f60: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
7f70: 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72  ill be.** zero r
7f80: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
7f90: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
7fa0: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
7fb0: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a  iginally in the.
7fc0: 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74  ** table. To get
7fd0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
7fe0: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
7ff0: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
8000: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
8010: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
8020: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
8030: 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
8040: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
8050: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
8060: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
8070: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69  ion.** while thi
8080: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
8090: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65  ning then the re
80a0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
80b0: 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73  is routine.** is
80c0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
80d0: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
80e0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
80f0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
8100: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
8110: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
8120: 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ery.**.** This f
8130: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
8140: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
8150: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
8160: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
8170: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
8180: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
8190: 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
81a0: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
81b0: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
81c0: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
81d0: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
81e0: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
81f0: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
8200: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
8210: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
8220: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
8230: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
8240: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20  *.** It is safe 
8250: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
8260: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
8270: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
8280: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
8290: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
82a0: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
82b0: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
82c0: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
82d0: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
82e0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
82f0: 74 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  th a database co
8300: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a  nnection that.**
8310: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
8320: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
8330: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
8340: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
8350: 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72  .** The SQL oper
8360: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
8370: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
8380: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
8390: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20  TERRUPT]..** If 
83a0: 61 6e 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f  an interrupted o
83b0: 70 65 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20  peration was an 
83c0: 75 70 64 61 74 65 20 74 68 61 74 20 69 73 20 69  update that is i
83d0: 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c  nside an.** expl
83e0: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
83f0: 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
8400: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69  e transaction wi
8410: 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20  ll be rolled.** 
8420: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
8430: 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ly..*/.void sqli
8440: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
8450: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
8460: 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
8470: 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
8480: 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
8490: 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
84a0: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
84b0: 20 74 72 75 65 20 69 66 20 74 68 65 20 67 69 76   true if the giv
84c0: 65 6e 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  en input string 
84d0: 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65  comprises.** one
84e0: 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74   or more complet
84f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
8500: 2e 20 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65  . For the sqlite
8510: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c  3_complete() cal
8520: 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65  l,.** the parame
8530: 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75  ter must be a nu
8540: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  l-terminated UTF
8550: 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a  -8 string. For.*
8560: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  * sqlite3_comple
8570: 74 65 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65  te16(), a nul-te
8580: 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65  rminated machine
8590: 20 62 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d   byte order UTF-
85a0: 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20  16 string.** is 
85b0: 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
85c0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
85d0: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
85e0: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
85f0: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
8600: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
8610: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 66  y entered text f
8620: 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  orms one or more
8630: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
8640: 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69  atements or.** i
8650: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
8660: 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
8670: 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
8680: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a  statements into.
8690: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
86a0: 72 73 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72  rsing. The algor
86b0: 69 74 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20  ithm is simple. 
86c0: 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74   If the .** last
86d0: 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61   token other tha
86e0: 6e 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d  n spaces and com
86f0: 6d 65 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63  ments is a semic
8700: 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72  olon, then retur
8710: 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74  n .** true.  Act
8720: 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72  ually, the algor
8730: 69 74 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65  ithm is a little
8740: 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
8750: 64 20 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69  d than that.** i
8760: 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20  n order to deal 
8770: 77 69 74 68 20 74 72 69 67 67 65 72 73 2c 20 62  with triggers, b
8780: 75 74 20 74 68 65 20 62 61 73 69 63 20 69 64 65  ut the basic ide
8790: 61 20 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20  a is the same:  
87a0: 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
87b0: 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65   is not complete
87c0: 20 75 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20   unless it ends 
87d0: 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a  in a semicolon..
87e0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
87f0: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
8800: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
8810: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
8820: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
8830: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8840: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
8850: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
8860: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
8870: 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  rors.**.** This 
8880: 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69  routine identifi
8890: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
88a0: 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
88b0: 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  t be invoked.** 
88c0: 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65  whenever an atte
88d0: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
88e0: 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
88f0: 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e  able .** that an
8900: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20  other thread or 
8910: 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
8920: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  ed..** If the bu
8930: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
8940: 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
8950: 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73  E_BUSY].** (or s
8960: 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45  ometimes [SQLITE
8970: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29  _IOERR_BLOCKED])
8980: 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
8990: 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
89a0: 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
89b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68  e lock..** If th
89c0: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
89d0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
89e0: 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63  n the.** callbac
89f0: 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
8a00: 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
8a10: 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69  ents.  The.** fi
8a20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
8a30: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
8a40: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
8a50: 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
8a60: 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
8a70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
8a80: 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20  s routine.  The 
8a90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
8aa0: 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  to.** the handle
8ab0: 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
8ac0: 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
8ad0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
8ae0: 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
8af0: 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
8b00: 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68  ing event. If th
8b10: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
8b20: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
8b30: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
8b40: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
8b50: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
8b60: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
8b70: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
8b80: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
8b90: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
8ba0: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  rned..** If the 
8bb0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
8bc0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
8bd0: 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20  another attempt 
8be0: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
8bf0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
8c00: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
8c10: 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
8c20: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
8c30: 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
8c40: 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
8c50: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a   guarantee that.
8c60: 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  ** it will be in
8c70: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65  voked when there
8c80: 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
8c90: 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ion..** If SQLit
8ca0: 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
8cb0: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
8cc0: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  usy handler coul
8cd0: 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61  d result in.** a
8ce0: 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
8cf0: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
8d00: 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e  E_BUSY] instead.
8d10: 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
8d20: 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
8d30: 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
8d40: 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
8d50: 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
8d60: 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
8d70: 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
8d80: 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
8d90: 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
8da0: 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
8db0: 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
8dc0: 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
8dd0: 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
8de0: 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
8df0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
8e00: 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
8e10: 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
8e20: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
8e30: 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
8e40: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
8e50: 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
8e60: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
8e70: 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
8e80: 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
8e90: 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
8ea0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
8eb0: 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
8ec0: 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
8ed0: 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
8ee0: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
8ef0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
8f00: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
8f10: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
8f20: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
8f30: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
8f40: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
8f50: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
8f60: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
8f70: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
8f80: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
8f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
8fa0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
8fb0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
8fc0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
8fd0: 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
8fe0: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
8ff0: 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a  R_BLOCKED] when.
9000: 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  ** SQLite is in 
9010: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
9020: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
9030: 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
9040: 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
9050: 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
9060: 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
9070: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
9080: 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
9090: 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
90a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
90b0: 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
90c0: 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
90d0: 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
90e0: 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
90f0: 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
9100: 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
9110: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9120: 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
9130: 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
9140: 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
9150: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
9160: 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
9170: 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
9180: 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
9190: 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
91a0: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
91b0: 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
91c0: 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
91d0: 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
91e0: 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
91f0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
9200: 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
9210: 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
9220: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
9230: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
9240: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
9250: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
9260: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
9270: 68 61 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a  hanges. See the.
9280: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70  ** <a href="http
9290: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
92a0: 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  g/cvstrac/wiki?p
92b0: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
92c0: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
92d0: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
92e0: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
92f0: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
9300: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
9310: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
9320: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a   important..**..
9330: 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d  ** Sqlite is re-
9340: 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20  entrant, so the 
9350: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79  busy handler may
9360: 20 73 74 61 72 74 20 61 20 6e 65 77 20 71 75 65   start a new que
9370: 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e  ry. .** (It is n
9380: 6f 74 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79  ot clear why any
9390: 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20  one would every 
93a0: 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c  want to do this,
93b0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c   but it.** is al
93c0: 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79  lowed, in theory
93d0: 2e 29 20 20 42 75 74 20 74 68 65 20 62 75 73 79  .)  But the busy
93e0: 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74   handler may not
93f0: 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61   close the.** da
9400: 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67  tabase.  Closing
9410: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
9420: 6f 6d 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  om a busy handle
9430: 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a  r will delete .*
9440: 2a 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  * data structure
9450: 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72  s out from under
9460: 20 74 68 65 20 65 78 65 63 75 74 69 6e 67 20 71   the executing q
9470: 75 65 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a  uery and will .*
9480: 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c  * probably resul
9490: 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
94a0: 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
94b0: 65 72 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72  er runtime error
94c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
94d0: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
94e0: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
94f0: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
9500: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9510: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e  nection.  Settin
9520: 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
9530: 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20  dler clears any 
9540: 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a  previous one..**
9550: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
9560: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
9570: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c  _timeout()] will
9580: 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
9590: 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  ar.** the busy h
95a0: 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68  andler..**.** Wh
95b0: 65 6e 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20  en operating in 
95c0: 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
95d0: 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73  shared_cache | s
95e0: 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
95f0: 5d 2c 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e  ],.** only a sin
9600: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
9610: 20 63 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20   can be defined 
9620: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
9630: 65 20 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66  e file..** So if
9640: 20 74 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f   two database co
9650: 6e 6e 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20  nnections share 
9660: 61 20 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20  a single cache, 
9670: 74 68 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a  then changing.**
9680: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
9690: 72 20 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74  r on one connect
96a0: 69 6f 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68  ion will also ch
96b0: 61 6e 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a  ange the busy.**
96c0: 20 68 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20   handler in the 
96d0: 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e  other connection
96e0: 2e 20 20 54 68 65 20 62 75 73 79 20 68 61 6e 64  .  The busy hand
96f0: 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ler is invoked.*
9700: 2a 20 69 6e 20 74 68 65 20 74 68 72 65 61 64 20  * in the thread 
9710: 74 68 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67  that was running
9720: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
9730: 5f 42 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a  _BUSY was hit..*
9740: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
9750: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
9760: 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
9770: 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
9780: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9790: 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
97a0: 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  out.**.** This r
97b0: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 62 75  outine sets a bu
97c0: 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20  sy handler that 
97d0: 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69  sleeps for a whi
97e0: 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62  le when a.** tab
97f0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
9800: 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  he handler will 
9810: 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
9820: 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61  imes until .** a
9830: 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
9840: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
9850: 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20  eping have been 
9860: 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20  done.  After.** 
9870: 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
9880: 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74  s of sleeping, t
9890: 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
98a0: 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61  ns 0 which.** ca
98b0: 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
98c0: 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  ep()] to return 
98d0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
98e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
98f0: 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
9900: 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
9910: 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
9920: 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
9930: 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
9940: 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
9950: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
9960: 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
9970: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
9980: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
9990: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  r a particular d
99a0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
99b0: 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68  ction.  If anoth
99c0: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
99d0: 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a  was defined  .**
99e0: 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
99f0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
9a00: 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
9a10: 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
9a20: 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
9a30: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
9a40: 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  leared..*/.int s
9a50: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
9a60: 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
9a70: 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
9a80: 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
9a90: 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
9aa0: 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
9ab0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74  .**.** This next
9ac0: 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f   routine is a co
9ad0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
9ae0: 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65  r around [sqlite
9af0: 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e  3_exec()]..** In
9b00: 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
9b10: 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65  g a user-supplie
9b20: 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65  d callback for e
9b30: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  ach row of the.*
9b40: 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72  * result, this r
9b50: 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73  outine remembers
9b60: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
9b70: 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72   result in memor
9b80: 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
9b90: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
9ba0: 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75  oc()], then retu
9bb0: 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72  rns all of the r
9bc0: 65 73 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a  esult after the.
9bd0: 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66 69 6e  ** query has fin
9be0: 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73  ished. .**.** As
9bf0: 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70   an example, sup
9c00: 70 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 72  pose the query r
9c10: 65 73 75 6c 74 20 77 68 65 72 65 20 74 68 69 73  esult where this
9c20: 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62   table:.**.** <b
9c30: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
9c40: 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
9c50: 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
9c60: 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
9c70: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
9c80: 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
9c90: 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
9ca0: 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
9cb0: 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
9cc0: 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
9cd0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
9ce0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uote>.**.** If t
9cf0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
9d00: 77 65 72 65 20 26 61 7a 52 65 73 75 6c 74 20 74  were &azResult t
9d10: 68 65 6e 20 61 66 74 65 72 20 74 68 65 20 66 75  hen after the fu
9d20: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a  nction returns.*
9d30: 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 6c 6c 20  * azResult will 
9d40: 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 6f 6c 6c  contain the foll
9d50: 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a 2a 0a 2a  owing data:.**.*
9d60: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
9d70: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
9d80: 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
9d90: 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
9da0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
9db0: 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
9dc0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
9dd0: 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
9de0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
9df0: 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
9e00: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
9e10: 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
9e20: 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
9e30: 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
9e40: 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
9e50: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
9e60: 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
9e70: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
9e80: 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
9e90: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
9ea0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63  ote>.**.** Notic
9eb0: 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  e that there is 
9ec0: 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20  an extra row of 
9ed0: 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20  data containing 
9ee0: 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65  the column.** he
9ef0: 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20  aders.  But the 
9f00: 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c  *nrow return val
9f10: 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20  ue is still 3.  
9f20: 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73  *ncolumn is.** s
9f30: 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e  et to 2.  In gen
9f40: 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72  eral, the number
9f50: 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72   of values inser
9f60: 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c  ted into azResul
9f70: 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a  t.** will be ((*
9f80: 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f  nrow) + 1)*(*nco
9f90: 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  lumn)..**.** Aft
9fa0: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
9fb0: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
9fc0: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
9fd0: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
9fe0: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65   .** pass the re
9ff0: 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65  sult data pointe
a000: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
a010: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
a020: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
a030: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
a040: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e  t was malloc-ed.
a050: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
a060: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
a070: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a080: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c  happens, the cal
a090: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
a0a0: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
a0b0: 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ll .** [sqlite3_
a0c0: 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
a0d0: 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33  .  Only [sqlite3
a0e0: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
a0f0: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
a100: 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  e .** the memory
a110: 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
a120: 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
a130: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
a140: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
a150: 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d  the same as from
a160: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
a170: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
a180: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
a190: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
a1a0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
a1b0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
a1c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
a1d0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
a1e0: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
a1f0: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
a200: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
a210: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
a220: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
a230: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
a240: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
a250: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
a260: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
a270: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
a280: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
a290: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
a2a0: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
a2b0: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
a2c0: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
a2d0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
a2e0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
a2f0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
a300: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
a310: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
a320: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
a330: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
a340: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
a350: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
a360: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
a370: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
a380: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
a390: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
a3a0: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
a3b0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
a3c0: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
a3d0: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
a3e0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
a3f0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
a400: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
a410: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
a420: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a430: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
a440: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
a450: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
a460: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
a470: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
a480: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
a490: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
a4a0: 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
a4b0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
a4c0: 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
a4d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
a4e0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
a4f0: 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
a500: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
a510: 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
a520: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
a530: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
a540: 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
a550: 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
a560: 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
a570: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
a580: 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
a590: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
a5a0: 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
a5b0: 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
a5c0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
a5d0: 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
a5e0: 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
a5f0: 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f  t parameter.  No
a600: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
a610: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
a620: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
a630: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
a640: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
a650: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
a660: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
a670: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
a680: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
a690: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
a6a0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
a6b0: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
a6c0: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
a6d0: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
a6e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
a6f0: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
a700: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
a710: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
a720: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
a730: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
a740: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
a750: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
a760: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
a770: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
a780: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
a790: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
a7a0: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
a7b0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
a7c0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
a7d0: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
a7e0: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
a7f0: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
a800: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
a810: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
a820: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
a830: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
a840: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
a850: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
a860: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
a870: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
a880: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
a890: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
a8a0: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
a8b0: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
a8c0: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
a8d0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
a8e0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
a8f0: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
a900: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
a910: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
a920: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
a930: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
a940: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
a950: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
a960: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
a970: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
a980: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
a990: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
a9a0: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
a9b0: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
a9c0: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
a9d0: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
a9e0: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
a9f0: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
aa00: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
aa10: 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
aa20: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
aa30: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
aa40: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
aa50: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
aa60: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
aa70: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
aa80: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
aa90: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
aaa0: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
aab0: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
aac0: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
aad0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
aae0: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
aaf0: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
ab00: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
ab10: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
ab20: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
ab30: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
ab40: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
ab50: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
ab60: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
ab70: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
ab80: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
ab90: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
aba0: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
abb0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
abc0: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
abd0: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
abe0: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
abf0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ac00: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
ac10: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
ac20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
ac30: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
ac40: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
ac50: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
ac60: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
ac70: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
ac80: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
ac90: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
aca0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
acb0: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
acc0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
acd0: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
ace0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
acf0: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
ad00: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
ad10: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
ad20: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
ad30: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
ad40: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
ad50: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
ad60: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
ad70: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
ad80: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
ad90: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
ada0: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
adb0: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
adc0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
add0: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
ade0: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
adf0: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
ae00: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
ae10: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
ae20: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
ae30: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
ae40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
ae50: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
ae60: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
ae70: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
ae80: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
ae90: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
aea0: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
aeb0: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
aec0: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
aed0: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
aee0: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
aef0: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
af00: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
af10: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
af20: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
af30: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
af40: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
af50: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
af60: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
af70: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
af80: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
af90: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
afa0: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
afb0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
afc0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
afd0: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
afe0: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
aff0: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
b000: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
b010: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
b020: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
b030: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
b040: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
b050: 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
b060: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
b070: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
b080: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
b090: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
b0a0: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
b0b0: 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
b0c0: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
b0d0: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
b0e0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
b0f0: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
b100: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
b110: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
b120: 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
b130: 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
b140: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
b150: 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
b160: 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
b170: 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
b180: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
b190: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
b1a0: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
b1b0: 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
b1c0: 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
b1d0: 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
b1e0: 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
b1f0: 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
b200: 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
b210: 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
b220: 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
b230: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
b240: 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
b250: 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..*/.char *sqlit
b260: 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
b270: 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
b280: 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
b290: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
b2a0: 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
b2b0: 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
b2c0: 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
b2d0: 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
b2e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b2f0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
b300: 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
b310: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
b320: 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
b330: 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
b340: 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
b350: 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
b360: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
b370: 64 73 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ds. The default 
b380: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
b390: 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20  * of the memory 
b3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
b3b0: 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61  stem uses the ma
b3c0: 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
b3d0: 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20  ).** and free() 
b3e0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
b3f0: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
b400: 72 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  ry.  However, if
b410: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 63   .** SQLite is c
b420: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
b430: 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65   following C pre
b440: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
b450: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
b460: 65 3e 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  e> SQLITE_OMIT_M
b470: 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
b480: 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
b490: 2a 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 69 6d 70  *.** then no imp
b4a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 70  lementation is p
b4b0: 72 6f 76 69 64 65 64 20 66 6f 72 20 74 68 65 73  rovided for thes
b4c0: 65 20 72 6f 75 74 69 6e 65 73 20 62 79 0a 2a 2a  e routines by.**
b4d0: 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 61 70   SQLite.  The ap
b4e0: 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
b4f0: 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
b500: 69 74 65 20 69 73 0a 2a 2a 20 65 78 70 65 63 74  ite is.** expect
b510: 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74  ed to provide it
b520: 73 20 6f 77 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  s own implementa
b530: 74 69 6f 6e 2e 20 20 49 66 20 74 68 65 20 61 70  tion.  If the ap
b540: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 64 6f 65  plication.** doe
b550: 73 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77  s provide its ow
b560: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
b570: 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
b580: 6e 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 69 74 20  nes, then.** it 
b590: 6d 75 73 74 20 61 6c 73 6f 20 70 72 6f 76 69 64  must also provid
b5a0: 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e an implementat
b5b0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ion for.** [sqli
b5c0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
b5d0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78  ()]..**.** <b>Ex
b5e0: 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65  ception:</b> The
b5f0: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   windows OS inte
b600: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
b610: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
b620: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
b630: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
b640: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
b650: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
b660: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
b670: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
b680: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
b690: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
b6a0: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
b6b0: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
b6c0: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  windows.** insta
b6d0: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
b6e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
b6f0: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
b700: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
b710: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
b720: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
b730: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
b740: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
b750: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
b760: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  EM]..*/.void *sq
b770: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
b780: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
b790: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
b7a0: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
b7b0: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
b7c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b7d0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
b7e0: 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
b7f0: 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** In addition t
b800: 6f 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65  o the basic thre
b810: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  e allocation rou
b820: 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  tines .** [sqlit
b830: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
b840: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
b850: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
b860: 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20  lloc()],.** the 
b870: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b880: 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c  n subsystem incl
b890: 75 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51  uded with the SQ
b8a0: 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20  Lite.** sources 
b8b0: 70 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74  provides the int
b8c0: 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20 62 65  erfaces shown be
b8d0: 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  low..**.** The f
b8e0: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 74 77  irst of these tw
b8f0: 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  o routines retur
b900: 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ns the amount of
b910: 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72   memory .** curr
b920: 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
b930: 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
b940: 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54 68 65  not freed).  The
b950: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72   second.** retur
b960: 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  ns the largest i
b970: 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f  nstantaneous amo
b980: 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69  unt of outstandi
b990: 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54  ng.** memory.  T
b9a0: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  he highwater mar
b9b0: 6b 20 69 73 20 72 65 73 65 74 20 69 66 20 74 68  k is reset if th
b9c0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  e argument is.**
b9d0: 20 74 72 75 65 2e 20 20 54 68 65 20 53 51 4c 69   true.  The SQLi
b9e0: 74 65 20 63 6f 72 65 20 64 6f 65 73 20 6e 6f 74  te core does not
b9f0: 20 75 73 65 20 65 69 74 68 65 72 20 6f 66 20 74   use either of t
ba00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
ba10: 20 61 6e 64 20 73 6f 20 74 68 65 79 20 64 6f 20   and so they do 
ba20: 6e 6f 74 20 68 61 76 65 20 74 6f 20 62 65 20 69  not have to be i
ba30: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
ba40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
ba50: 20 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f   if SQLITE_OMIT_
ba60: 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
ba70: 4e 20 69 73 20 64 65 66 69 6e 65 64 2e 20 20 54  N is defined.  T
ba80: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
ba90: 20 61 72 65 20 70 72 6f 76 69 64 65 64 20 62 79   are provided by
baa0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
bab0: 6f 72 79 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ory subsystem fo
bac0: 72 20 64 69 61 67 6e 6f 73 74 69 63 0a 2a 2a 20  r diagnostic.** 
bad0: 70 75 72 70 6f 73 65 73 2e 0a 2a 2f 0a 73 71 6c  purposes..*/.sql
bae0: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
baf0: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
bb00: 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
bb10: 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
bb20: 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
bb30: 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
bb40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
bb50: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
bb60: 41 6c 61 72 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Alarms.**.** The
bb70: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
bb80: 5f 61 6c 61 72 6d 5d 20 72 6f 75 74 69 6e 65 20  _alarm] routine 
bb90: 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  is used to regis
bba0: 74 65 72 0a 2a 2a 20 61 20 63 61 6c 6c 62 61 63  ter.** a callbac
bbb0: 6b 20 6f 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  k on memory allo
bbc0: 63 61 74 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a  cation events..*
bbd0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
bbe0: 65 20 72 65 67 69 73 74 65 72 73 20 6f 72 20 63  e registers or c
bbf0: 6c 65 61 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  lears a callback
bc00: 73 20 74 68 61 74 20 66 69 72 65 73 20 77 68 65  s that fires whe
bc10: 6e 0a 2a 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20  n.** the amount 
bc20: 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
bc30: 74 65 64 20 65 78 63 65 65 64 73 20 69 54 68 72  ted exceeds iThr
bc40: 65 73 68 6f 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a  eshold.  Only.**
bc50: 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
bc60: 63 6b 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ck can be regist
bc70: 65 72 65 64 20 61 74 20 61 20 74 69 6d 65 2e 20  ered at a time. 
bc80: 20 45 61 63 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f   Each call.** to
bc90: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
bca0: 5f 61 6c 61 72 6d 28 29 5d 20 6f 76 65 72 77 72  _alarm()] overwr
bcb0: 69 74 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ites the previou
bcc0: 73 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  s callback..** T
bcd0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 64  he callback is d
bce0: 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
bcf0: 6e 67 20 78 43 61 6c 6c 62 61 63 6b 20 74 6f 20  ng xCallback to 
bd00: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
bd10: 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 70 61  r..** .** The pa
bd20: 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
bd30: 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 74 68 65  callback are the
bd40: 20 70 41 72 67 20 76 61 6c 75 65 2c 20 74 68 65   pArg value, the
bd50: 20 0a 2a 2a 20 61 6d 6f 75 6e 74 20 6f 66 20 6d   .** amount of m
bd60: 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
bd70: 69 6e 20 75 73 65 2c 20 61 6e 64 20 74 68 65 20  in use, and the 
bd80: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61  size of the.** a
bd90: 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 70  llocation that p
bda0: 72 6f 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  rovoked the call
bdb0: 62 61 63 6b 2e 20 20 54 68 65 20 63 61 6c 6c 62  back.  The callb
bdc0: 61 63 6b 20 77 69 6c 6c 0a 2a 2a 20 70 72 65 73  ack will.** pres
bdd0: 75 6d 61 62 6c 79 20 69 6e 76 6f 6b 65 20 5b 73  umably invoke [s
bde0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74  qlite3_free()] t
bdf0: 6f 20 66 72 65 65 20 75 70 20 6d 65 6d 6f 72 79  o free up memory
be00: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 63   space..** The c
be10: 61 6c 6c 62 61 63 6b 20 6d 61 79 20 69 6e 76 6f  allback may invo
be20: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ke [sqlite3_mall
be30: 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
be40: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
be50: 62 75 74 20 69 66 20 69 74 20 64 6f 65 73 2c 20  but if it does, 
be60: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  no additional ca
be70: 6c 6c 62 61 63 6b 73 20 77 69 6c 6c 20 62 65 20  llbacks will be 
be80: 69 6e 76 6f 6b 65 64 20 62 79 0a 2a 2a 20 74 68  invoked by.** th
be90: 65 20 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c  e recursive call
bea0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  s..**.** The [sq
beb0: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
bec0: 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
bed0: 63 65 20 77 6f 72 6b 73 20 62 79 20 72 65 67 69  ce works by regi
bee0: 73 74 65 72 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d  stering.** a mem
bef0: 6f 72 79 20 61 6c 61 72 6d 20 61 74 20 74 68 65  ory alarm at the
bf00: 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
bf10: 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a   and invoking .*
bf20: 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
bf30: 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 20  se_memory()] in 
bf40: 74 68 65 20 61 6c 61 72 6d 20 63 61 6c 6c 62 61  the alarm callba
bf50: 63 6b 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ck.  Application
bf60: 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 20 73 68 6f  .** programs sho
bf70: 75 6c 64 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  uld not attempt 
bf80: 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
bf90: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
bfa0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
bfb0: 20 62 65 63 61 75 73 65 20 64 6f 69 6e 67 20 73   because doing s
bfc0: 6f 20 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65  o will interfere
bfd0: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
bfe0: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
bff0: 6c 69 6d 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e  limit()] module.
c000: 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
c010: 20 69 73 20 65 78 70 6f 73 65 64 0a 2a 2a 20 6f   is exposed.** o
c020: 6e 6c 79 20 73 6f 20 74 68 61 74 20 61 70 70 6c  nly so that appl
c030: 69 63 61 74 69 6f 6e 73 20 63 61 6e 20 70 72 6f  ications can pro
c040: 76 69 64 65 20 74 68 65 69 72 20 6f 77 6e 0a 2a  vide their own.*
c050: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  * alternative im
c060: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
c070: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
c080: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
c090: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49   with SQLITE_OMI
c0a0: 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
c0b0: 49 4f 4e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ION..*/.int sqli
c0c0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
c0d0: 28 0a 20 20 76 6f 69 64 28 2a 78 43 61 6c 6c 62  (.  void(*xCallb
c0e0: 61 63 6b 29 28 76 6f 69 64 20 2a 70 41 72 67 2c  ack)(void *pArg,
c0f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 75   sqlite3_int64 u
c100: 73 65 64 2c 20 69 6e 74 20 4e 29 2c 0a 20 20 76  sed, int N),.  v
c110: 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c  oid *pArg,.  sql
c120: 69 74 65 33 5f 69 6e 74 36 34 20 69 54 68 72 65  ite3_int64 iThre
c130: 73 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  shold.);.../*.**
c140: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
c150: 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
c160: 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
c170: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ***.** This rout
c180: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
c190: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
c1a0: 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c  ack with the SQL
c1b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a  ite library.  .*
c1c0: 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
c1d0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
c1e0: 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
c1f0: 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
c200: 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
c210: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
c220: 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
c230: 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
c240: 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
c250: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
c260: 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
c270: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
c280: 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
c290: 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
c2a0: 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
c2b0: 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
c2c0: 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
c2d0: 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
c2e0: 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
c2f0: 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
c300: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
c310: 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
c320: 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
c330: 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
c340: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
c350: 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
c360: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c370: 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
c380: 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
c390: 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
c3a0: 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
c3b0: 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
c3c0: 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
c3d0: 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
c3e0: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
c3f0: 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
c400: 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
c410: 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
c420: 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
c430: 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
c440: 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20   error.  .**.** 
c450: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  Depending on the
c460: 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51   action, the [SQ
c470: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64  LITE_IGNORE] and
c480: 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72   [SQLITE_DENY] r
c490: 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d  eturn.** codes m
c4a0: 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68  ight mean someth
c4b0: 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72  ing different or
c4c0: 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e   they might mean
c4d0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69   the same.** thi
c4e0: 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69  ng.  If the acti
c4f0: 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70  on is, for examp
c500: 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61  le, to perform a
c510: 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e   delete opertion
c520: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54  ,.** then [SQLIT
c530: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
c540: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68  QLITE_DENY] both
c550: 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65   cause the state
c560: 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  ment compilation
c570: 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68  .** to fail with
c580: 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20   an error.  But 
c590: 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  if the action is
c5a0: 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69   to read a speci
c5b0: 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72  fic column.** fr
c5c0: 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61  om a specific ta
c5d0: 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ble, then [SQLIT
c5e0: 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75  E_DENY] will cau
c5f0: 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a  se the entire.**
c600: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61   statement to fa
c610: 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49  il but [SQLITE_I
c620: 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73  GNORE] will caus
c630: 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74  e a NULL value t
c640: 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73  o be.** read ins
c650: 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75  tead of the actu
c660: 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  al column value.
c670: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
c680: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
c690: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
c6a0: 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
c6b0: 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  of.** the third 
c6c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
c6d0: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
c6e0: 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
c6f0: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ace..** The seco
c700: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
c710: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
c720: 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b  an integer .** [
c730: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
c740: 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
c750: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
c760: 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
c770: 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  ** to be authori
c780: 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61  zed.  The availa
c790: 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ble action codes
c7a0: 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   are.** [SQLITE_
c7b0: 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65  COPY | documente
c7c0: 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20  d separately].  
c7d0: 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
c7e0: 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
c7f0: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
c800: 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67  lback are string
c810: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
c820: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
c830: 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
c840: 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
c850: 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
c860: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
c870: 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69  sed when prepari
c880: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
c890: 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
c8a0: 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74  ted.** source, t
c8b0: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
c8c0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
c8d0: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
c8e0: 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68  ccess data.** th
c8f0: 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  at they are not 
c900: 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
c910: 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
c920: 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78  not try to.** ex
c930: 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
c940: 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
c950: 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
c960: 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
c970: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
c980: 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
c990: 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
c9a0: 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
c9b0: 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
c9c0: 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
c9d0: 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
c9e0: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
c9f0: 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
ca00: 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
ca10: 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
ca20: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
ca30: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
ca40: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
ca50: 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
ca60: 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
ca70: 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
ca80: 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70  d SQL is being p
ca90: 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73  repared that dis
caa0: 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
cab0: 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45  g.** except SELE
cac0: 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  CT statements.  
cad0: 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
cae0: 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
caf0: 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
cb00: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
cb10: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
cb20: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
cb30: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
cb40: 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
cb50: 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
cb60: 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e  vious call.  A N
cb70: 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
cb80: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
cb90: 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
cba0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
cbb0: 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
cbc0: 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55  authorizer is NU
cbd0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  LL..**.** Note t
cbe0: 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
cbf0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
cc00: 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
cc10: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
cc20: 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
cc30: 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
cc40: 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
cc50: 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
cc60: 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
cc70: 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
cc80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
cc90: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
cca0: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
ccb0: 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
ccc0: 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
ccd0: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
cce0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
ccf0: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
cd00: 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
cd10: 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
cd20: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
cd30: 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
cd40: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
cd50: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
cd60: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
cd70: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
cd80: 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
cd90: 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
cda0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
cdb0: 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
cdc0: 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
cdd0: 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
cde0: 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
cdf0: 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
ce00: 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
ce10: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
ce20: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
ce30: 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
ce40: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
ce50: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
ce60: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
ce80: 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
ce90: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
cea0: 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
ceb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cec0: 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
ced0: 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
cee0: 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
cef0: 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
cf00: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
cf10: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
cf20: 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
cf30: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
cf40: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
cf50: 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
cf60: 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
cf70: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
cf80: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
cf90: 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69  uthorizer certai
cfa0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
cfb0: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
cfc0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
cfd0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
cfe0: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
cff0: 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
d000: 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
d010: 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
d020: 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
d030: 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
d040: 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
d050: 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
d060: 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
d070: 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
d080: 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
d090: 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
d0a0: 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
d0b0: 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
d0c0: 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  e .** authorized
d0d0: 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
d0e0: 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
d0f0: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
d100: 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  on callback.** f
d110: 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
d120: 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
d130: 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
d140: 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
d150: 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
d160: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
d170: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
d180: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
d190: 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
d1a0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
d1b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
d1c0: 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
d1d0: 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29  temp", .** etc.)
d1e0: 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
d1f0: 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
d200: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
d210: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
d220: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
d230: 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
d240: 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
d250: 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
d260: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
d270: 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
d280: 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
d290: 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
d2a0: 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
d2b0: 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
d2c0: 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
d2d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d2e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d2f0: 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
d300: 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
d310: 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
d320: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
d330: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
d340: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
d350: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
d360: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d370: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
d380: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
d390: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
d3a0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
d3b0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d3c0: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
d3d0: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
d3e0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
d3f0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d400: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d410: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
d420: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
d430: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d440: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d450: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d460: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
d470: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
d480: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
d490: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
d4a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d4b0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
d4c0: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
d4d0: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
d4e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
d4f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d500: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
d510: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
d520: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
d530: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
d540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d550: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
d560: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
d570: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
d580: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
d590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
d5a0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
d5b0: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
d5c0: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
d5d0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
d5e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
d5f0: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
d600: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
d610: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
d620: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
d630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
d640: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
d650: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
d660: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
d670: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
d680: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
d690: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
d6a0: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
d6b0: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
d6c0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
d6d0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
d6e0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
d6f0: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
d700: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
d710: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
d720: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
d730: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
d740: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
d750: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
d760: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d770: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
d780: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
d790: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
d7a0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
d7b0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d7c0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
d7d0: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
d7e0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
d7f0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
d800: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d810: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
d820: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
d830: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
d840: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d850: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d860: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
d870: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
d880: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
d890: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
d8a0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d8b0: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
d8c0: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
d8d0: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
d8e0: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
d8f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d900: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
d910: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
d920: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d930: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
d940: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d950: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
d960: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
d970: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
d980: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d990: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d9a0: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
d9b0: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
d9c0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
d9d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
d9e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d9f0: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
da00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
da10: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
da20: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
da30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
da40: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
da50: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
da60: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
da70: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
da80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
da90: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
daa0: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
dab0: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
dac0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
dad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
dae0: 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
daf0: 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
db00: 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
db10: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
db20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
db30: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
db40: 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
db50: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
db60: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
db70: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
db80: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
db90: 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
dba0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
dbb0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
dbc0: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
dbd0: 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
dbe0: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
dbf0: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
dc00: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
dc10: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
dc20: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
dc30: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
dc40: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
dc50: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
dc60: 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
dc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
dc80: 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
dc90: 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
dca0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
dcb0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
dcc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
dcd0: 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
dce0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
dcf0: 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
dd00: 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
dd10: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
dd20: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
dd30: 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
dd40: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
dd50: 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
dd60: 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
dd70: 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
dd80: 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
dd90: 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61  ments..** The ca
dda0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
ddb0: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
ddc0: 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
ddd0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74   invoked.** at t
dde0: 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65  he first [sqlite
ddf0: 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68  3_step()] for th
de00: 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
de10: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
de20: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
de30: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
de40: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
de50: 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
de60: 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
de70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
de80: 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c  inishes and incl
de90: 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  udes.** informat
dea0: 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20  ion on how long 
deb0: 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72  that statement r
dec0: 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  an..**.** The sq
ded0: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
dee0: 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79  API is currently
def0: 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
df00: 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20  rimental and.** 
df10: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
df20: 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ange..*/.void *s
df30: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
df40: 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
df50: 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
df60: 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
df70: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
df80: 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
df90: 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
dfa0: 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
dfb0: 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
dfc0: 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
dfd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dfe0: 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
dff0: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
e000: 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
e010: 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
e020: 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
e030: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
e040: 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ck - that.** is 
e050: 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
e060: 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
e070: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
e080: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
e090: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
e0a0: 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
e0b0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
e0c0: 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
e0d0: 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
e0e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
e0f0: 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
e100: 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
e110: 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  e query..**.** T
e120: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
e130: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
e140: 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
e150: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
e160: 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65   opcodes,.** whe
e170: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
e180: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
e190: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
e1a0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e1b0: 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73  ack.** itself is
e1c0: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
e1d0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
e1e0: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
e1f0: 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  on. The fourth.*
e200: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
e210: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
e220: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
e230: 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
e240: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
e250: 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
e260: 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
e270: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
e280: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ll to [sqlite3_e
e290: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
e2a0: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71  _step()], or [sq
e2b0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
e2c0: 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  )].** results in
e2d0: 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
e2e0: 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
e2f0: 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
e300: 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c  rogress .** call
e310: 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
e320: 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e  voked..** .** On
e330: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
e340: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75  ress callback fu
e350: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
e360: 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63  gistered for eac
e370: 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  h.** open databa
e380: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
e390: 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71  Every call to sq
e3a0: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
e3b0: 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72  andler().** over
e3c0: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
e3d0: 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  ts of the previo
e3e0: 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72  us call..** To r
e3f0: 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65  emove the progre
e400: 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f  ss callback alto
e410: 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c  gether, pass NUL
e420: 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  L as the third.*
e430: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
e440: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
e450: 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
e460: 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
e470: 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
e480: 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20  er than 0, then 
e490: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
e4a0: 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61  query is immedia
e4b0: 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20  tely terminated 
e4c0: 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65  and any database
e4d0: 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20   changes rolled 
e4e0: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e  back..** The con
e4f0: 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33  taining [sqlite3
e500: 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
e510: 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a  e3_step()], or.*
e520: 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
e530: 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74  able()] call ret
e540: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45  urns SQLITE_INTE
e550: 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65  RRUPT.   This fe
e560: 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20  ature.** can be 
e570: 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
e580: 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  e, to implement 
e590: 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74  the "Cancel" but
e5a0: 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67  ton on a.** prog
e5b0: 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20  ress dialog box 
e5c0: 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69  in a GUI..*/.voi
e5d0: 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
e5e0: 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
e5f0: 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
e600: 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
e610: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e620: 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
e630: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
e640: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74  ion.**.** Open t
e650: 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61  he sqlite databa
e660: 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d  se file "filenam
e670: 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61  e".  The "filena
e680: 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20  me" is UTF-8.** 
e690: 65 6e 63 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c  encoded for [sql
e6a0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
e6b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e6c0: 32 28 29 5d 20 61 6e 64 20 55 54 46 2d 31 36 20  2()] and UTF-16 
e6d0: 65 6e 63 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68  encoded.** in th
e6e0: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
e6f0: 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
e700: 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41  _open16()]..** A
e710: 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  n [sqlite3*] han
e720: 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  dle is returned 
e730: 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
e740: 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
e750: 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74  curs. If the dat
e760: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
e770: 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  (or created) suc
e780: 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68  cessfully,.** th
e790: 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
e7a0: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
e7b0: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
e7c0: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
e7d0: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
e7e0: 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
e7f0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
e800: 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  )]  routines can
e810: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e820: 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
e830: 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
e840: 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
e850: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
e860: 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
e870: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
e880: 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
e890: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
e8a0: 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
e8b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63  _open_v2()] is c
e8c0: 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
e8d0: 2d 31 36 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  -16 if [sqlite3_
e8e0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
e8f0: 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
e900: 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
e910: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
e920: 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
e930: 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a  rces associated.
e940: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
e950: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
e960: 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
e970: 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
e980: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c  o.** [sqlite3_cl
e990: 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
e9a0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
e9b0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
e9c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
e9d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
e9e0: 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
e9f0: 33 5f 6f 70 65 6e 28 29 5d 20 65 78 63 65 70 74  3_open()] except
ea00: 20 74 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65   that.** provide
ea10: 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
ea20: 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
ea30: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
ea40: 6f 6c 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e  ol over the.** n
ea50: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
ea60: 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
ea70: 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
ea80: 20 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a   be one of:.**.*
ea90: 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ol>.** <li>  
eaa0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
eab0: 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  DONLY].** <li>  
eac0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
ead0: 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  DWRITE].** <li> 
eae0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
eaf0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
eb00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a  TE_OPEN_CREATE].
eb10: 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ol>.**.** T
eb20: 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f  he first value o
eb30: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
eb40: 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66  e read-only.  If
eb50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
eb60: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f  es.** not previo
eb70: 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
eb80: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
eb90: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70  .  The second op
eba0: 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68  tion opens.** th
ebb0: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
ebc0: 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
ebd0: 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
ebe0: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
ebf0: 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  if.** if the fil
ec00: 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
ec10: 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72  cted.  In either
ec20: 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
ec30: 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a  se must already.
ec40: 2a 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65  ** exist or an e
ec50: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
ec60: 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74  .  The third opt
ec70: 69 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61  ion opens the da
ec80: 74 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65  tabase.** for re
ec90: 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
eca0: 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74  g and creates it
ecb0: 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
ecc0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a  already exist..*
ecd0: 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  * The third opti
ece0: 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20  ons is behavior 
ecf0: 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
ed00: 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  sed for [sqlite3
ed10: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
ed20: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
ed30: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
ed40: 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
ed50: 65 6d 6f 72 79 3a 22 20 6f 72 20 61 6e 20 65 6d  emory:" or an em
ed60: 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
ed70: 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69   an private.** i
ed80: 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
ed90: 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
eda0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
edb0: 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79    This in-memory
edc0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c  .** database wil
edd0: 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68  l vanish when th
ede0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
edf0: 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
ee00: 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
ee10: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ion of SQLite mi
ee20: 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  ght make use of 
ee30: 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
ee40: 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  al filenames.** 
ee50: 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
ee60: 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
ee70: 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  r.  It is recomm
ee80: 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77  ended that .** w
ee90: 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
eea0: 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64  ilename really d
eeb0: 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
eec0: 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70  * ":" that you p
eed0: 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
eee0: 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
eef0: 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a  me like "./" to.
ef00: 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  ** avoid ambigui
ef10: 74 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ty..**.** The fo
ef20: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
ef30: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
ef40: 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
ef50: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
ef60: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
ef70: 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
ef80: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
ef90: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74   .** interface t
efa0: 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61  hat the new data
efb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
efc0: 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
efd0: 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
efe0: 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c  rameter is a NUL
eff0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
f000: 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
f010: 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65  te3_vfs].** obje
f020: 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
f030: 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e  * <b>Note to win
f040: 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
f050: 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
f060: 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
f070: 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
f080: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
f090: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
f0a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74  _open_v2()] must
f0b0: 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
f0c0: 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
f0d0: 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
f0e0: 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
f0f0: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
f100: 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
f110: 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
f120: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
f130: 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
f140: 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
f150: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  o.** [sqlite3_op
f160: 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
f170: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  3_open_v2()]..*/
f180: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
f190: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
f1a0: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
f1b0: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
f1c0: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
f1d0: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
f1e0: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
f1f0: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
f200: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
f210: 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
f220: 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
f230: 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
f240: 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
f250: 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
f260: 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
f270: 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
f280: 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
f290: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
f2a0: 32 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  2(.  const void 
f2b0: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
f2c0: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
f2d0: 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
f2e0: 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
f2f0: 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
f300: 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
f310: 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
f320: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
f330: 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
f340: 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
f350: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
f360: 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
f370: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
f380: 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
f390: 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
f3a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f3b0: 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
f3c0: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
f3d0: 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
f3e0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
f3f0: 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
f400: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
f410: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
f420: 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
f430: 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
f440: 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
f450: 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
f460: 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
f470: 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
f480: 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
f490: 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
f4a0: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
f4b0: 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
f4c0: 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
f4d0: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
f4e0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
f4f0: 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  * is undefined. 
f500: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f510: 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
f520: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
f530: 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
f540: 68 2d 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65  h-langauge.** te
f550: 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
f560: 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
f570: 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
f580: 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
f590: 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
f5a0: 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
f5b0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
f5c0: 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
f5d0: 6c 6c 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74  lly.  The .** st
f5e0: 72 69 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72  ring may be over
f5f0: 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
f600: 6f 63 61 74 65 64 20 62 79 20 73 75 62 73 65 71  ocated by subseq
f610: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51  uent calls to SQ
f620: 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  Lite.** interfac
f630: 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
f640: 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79  ** Calls to many
f650: 20 73 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74   sqlite3_* funct
f660: 69 6f 6e 73 20 73 65 74 20 74 68 65 20 65 72 72  ions set the err
f670: 6f 72 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69  or code and stri
f680: 6e 67 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ng returned.** b
f690: 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
f6a0: 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
f6b0: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
f6c0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
f6d0: 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74  ()].** (overwrit
f6e0: 69 6e 67 20 74 68 65 20 70 72 65 76 69 6f 75 73  ing the previous
f6f0: 20 76 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74   values). Note t
f700: 68 61 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hat calls to [sq
f710: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
f720: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  ,.** [sqlite3_er
f730: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
f740: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
f750: 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  ] themselves do 
f760: 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a  not affect the.*
f770: 2a 20 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74  * results of fut
f780: 75 72 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  ure invocations.
f790: 20 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72    Calls to API r
f7a0: 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
f7b0: 6e 6f 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e  not return.** an
f7c0: 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
f7d0: 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
f7e0: 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
f7f0: 20 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74   not.** change t
f800: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65  he error code re
f810: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
f820: 6f 75 74 69 6e 65 2e 20 20 49 6e 74 65 72 66 61  outine.  Interfa
f830: 63 65 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ces that are.** 
f840: 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  not associated w
f850: 69 74 68 20 61 20 73 70 65 63 69 66 69 63 20 64  ith a specific d
f860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f870: 6f 6e 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  on (examples:.**
f880: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
f890: 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  f()] or [sqlite3
f8a0: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
f8b0: 61 63 68 65 28 29 5d 20 64 6f 20 6e 6f 74 20 63  ache()] do not c
f8c0: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
f8d0: 75 72 6e 20 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  urn code.  .**.*
f8e0: 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74  * Assuming no ot
f8f0: 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  her intervening 
f900: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
f910: 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68  lls are made, th
f920: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
f930: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
f940: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73   function is ass
f950: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
f960: 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a   same error as.*
f970: 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65  * the strings re
f980: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
f990: 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
f9a0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
f9b0: 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
f9c0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
f9d0: 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
f9e0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
f9f0: 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
fa00: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
fa10: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
fa20: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
fa30: 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
fa40: 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
fa50: 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f  **.** Instance o
fa60: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
fa70: 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53  present single S
fa80: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
fa90: 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f  This.** is vario
faa0: 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
fab0: 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
fac0: 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
fad0: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
fae0: 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
faf0: 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
fb00: 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
fb10: 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
fb20: 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
fb30: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
fb40: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
fb50: 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
fb60: 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
fb70: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
fb80: 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
fb90: 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
fba0: 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
fbb0: 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
fbc0: 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
fbd0: 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
fbe0: 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
fbf0: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
fc00: 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
fc10: 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
fc20: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
fc30: 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
fc40: 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
fc50: 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
fc60: 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
fc70: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
fc80: 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
fc90: 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
fca0: 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
fcb0: 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
fcc0: 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
fcd0: 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
fce0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
fcf0: 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
fd00: 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
fd10: 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
fd20: 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
fd30: 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
fd40: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
fd50: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
fd60: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
fd70: 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
fd80: 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
fd90: 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
fda0: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
fdb0: 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
fdc0: 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
fdd0: 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
fde0: 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
fdf0: 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
fe00: 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
fe10: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fe20: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73   .**.** The firs
fe30: 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20  t argument "db" 
fe40: 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c  is an [sqlite3 |
fe50: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
fe60: 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74   handle] .** obt
fe70: 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
fe80: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
fe90: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
fea0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
feb0: 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  ]..** The second
fec0: 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22   argument "zSql"
fed0: 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
fee0: 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
fef0: 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
ff00: 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
ff10: 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
ff20: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
ff30: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
ff40: 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
ff50: 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38  faces uses UTF-8
ff60: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
ff70: 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
ff80: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
ff90: 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
ffa0: 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
ffb0: 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
ffc0: 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a  s less.** than z
ffd0: 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
ffe0: 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
fff0: 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
10000 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e  inator.  If.** n
10010 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
10020 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
10030 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
10040 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73  ber of .** bytes
10050 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
10060 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
10070 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
10080 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
10090 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
100a0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
100b0 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a   character or .*
100c0 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74  * until the nByt
100d0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
100e0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
100f0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
10100 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
10110 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
10120 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
10130 6f 66 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  of the first.** 
10140 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
10150 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72 6f 75   zSql.  This rou
10160 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c  tine only compil
10170 65 73 20 74 68 65 20 66 69 72 73 74 20 73 74 61  es the first sta
10180 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71  tement.** in zSq
10190 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
101a0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
101b0 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  o what remains u
101c0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
101d0 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
101e0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
101f0 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c  ompiled .** [sql
10200 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
10210 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63 74  statement struct
10220 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ure] that can be
10230 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
10240 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
10250 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
10260 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
10270 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a  ppStmt may be.**
10280 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49   set to NULL.  I
10290 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
102a0 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51   contained no SQ
102b0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
102c0 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20  is and.** empty 
102d0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
102e0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
102f0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
10300 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  .  The calling.*
10310 2a 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  * procedure is r
10320 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
10330 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
10340 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
10350 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  nt.** using [sql
10360 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
10370 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
10380 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
10390 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
103a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
103b0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
103c0 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51  rwise an .** [SQ
103d0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72  LITE_ERROR | err
103e0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
103f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
10400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
10410 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
10420 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
10430 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
10440 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
10450 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
10460 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
10470 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
10480 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
10490 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
104a0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
104b0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
104c0 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68  uraged..** In th
104d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
104e0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
104f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
10500 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
10510 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
10520 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
10530 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
10540 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51   .** original SQ
10550 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
10560 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
10570 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
10580 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
10590 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
105a0 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
105b0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
105c0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
105d0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
105e0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
105f0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
10600 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
10610 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
10620 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
10630 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
10640 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
10650 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
10660 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
10670 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
10680 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
10690 20 63 68 61 6e 67 65 64 20 69 6e 20 61 20 77 61   changed in a wa
106a0 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65 73 20  y.** that makes 
106b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
106c0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
106d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
106e0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
106f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
10700 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
10710 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
10720 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
10730 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
10740 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
10750 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
10760 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
10770 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
10780 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
10790 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
107a0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
107b0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
107c0 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20  the text of the 
107d0 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72  parsing.** error
107e0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
107f0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
10800 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
10810 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
10820 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
10830 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71   occurs, .** [sq
10840 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
10850 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
10860 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a   the detailed .*
10870 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
10880 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  | result codes] 
10890 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
108a0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
108b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
108c0 5d 20 73 75 63 68 20 61 73 20 64 69 72 65 63 74  ] such as direct
108d0 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63  ly..** The legac
108e0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
108f0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hat [sqlite3_ste
10900 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
10910 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
10920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
10930 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  R] result code a
10940 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
10950 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
10960 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nd call to.** [s
10970 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
10980 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
10990 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
109a0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
109b0 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  blem..** With th
109c0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69  e "v2" prepare i
109d0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
109e0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
109f0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
10a00 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d  s.** returned im
10a10 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
10a20 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
10a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
10a40 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
10a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
10a60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
10a70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
10a80 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
10a90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
10aa0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
10ab0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
10ac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
10ad0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
10ae0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
10af0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
10b00 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
10b10 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
10b20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
10b30 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
10b40 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
10b50 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
10b60 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
10b70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
10b80 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
10b90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
10ba0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
10bb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10bc0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
10bd0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
10be0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
10bf0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
10c00 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
10c10 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
10c20 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
10c30 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
10c40 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
10c50 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
10c60 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
10c70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
10c80 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
10c90 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
10ca0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
10cb0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
10cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
10cd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
10ce0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
10cf0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
10d00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
10d10 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
10d20 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
10d30 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
10d40 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
10d50 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
10d60 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
10d70 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
10d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
10d90 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
10da0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
10db0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
10dc0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
10dd0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
10de0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
10df0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
10e00 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
10e10 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
10e20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
10e30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
10e40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
10e50 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
10e60 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
10e70 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
10e80 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
10e90 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
10ea0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
10eb0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
10ec0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
10ed0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
10ee0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
10ef0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
10f00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
10f10 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
10f20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
10f30 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
10f40 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
10f50 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
10f60 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
10f70 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53  e Object.**.** S
10f80 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
10f90 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68  ic typing for th
10fa0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
10fb0 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61 6e 20  es.  Values can 
10fc0 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c  .** be integers,
10fd0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
10fe0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
10ff0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
11000 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e    When.** passin
11010 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65 73 20  g around values 
11020 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68  internally, each
11030 20 76 61 6c 75 65 20 69 73 20 72 65 70 72 65 73   value is repres
11040 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69  ented as.** an i
11050 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
11060 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
11070 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
11080 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
11090 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
110a0 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
110b0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
110c0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
110d0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
110e0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
110f0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
11100 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
11110 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
11120 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
11130 72 20 74 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a  r to such an obj
11140 65 63 74 20 69 73 20 74 68 65 0a 2a 2a 20 66 69  ect is the.** fi
11150 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
11160 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51   user-defined SQ
11170 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a  L functions..*/.
11180 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11190 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
111a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
111b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
111c0 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73    Binding Values
111d0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
111e0 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e  tements.**.** In
111f0 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
11200 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
11210 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
11220 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
11230 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  s,.** one or mor
11240 65 20 6c 69 74 65 72 61 6c 73 20 63 61 6e 20 62  e literals can b
11250 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70  e replace by a p
11260 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20  arameter in one 
11270 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d  of these.** form
11280 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
11290 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
112a0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
112b0 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41  :AAA.** <li>  @A
112c0 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  AA.** <li>  $VVV
112d0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
112e0 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
112f0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
11300 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
11310 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
11320 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61   AAA is an alpha
11330 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
11340 65 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20  er and VVV is a 
11350 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63  variable name ac
11360 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  cording.** to th
11370 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f  e syntax rules o
11380 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61  f the TCL progra
11390 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a  mming language..
113a0 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  ** The values of
113b0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
113c0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
113d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
113e0 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ames").** can be
113f0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
11400 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
11410 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
11420 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
11430 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11440 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
11450 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
11460 20 61 6c 77 61 79 73 20 69 73 20 61 20 70 6f 69   always is a poi
11470 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
11480 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
11490 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
114a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
114b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
114c0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 54  its variants.  T
114d0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
114e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
114f0 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ex of the parame
11500 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 20  ter to be set.  
11510 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
11520 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e  ter has.** an in
11530 64 65 78 20 6f 66 20 31 2e 20 57 68 65 6e 20 74  dex of 1. When t
11540 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 20 70 61  he same named pa
11550 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
11560 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
11570 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75  second.** and su
11580 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
11590 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
115a0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
115b0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
115c0 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 65 78 20  nce.  The index 
115d0 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72  for.** named par
115e0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
115f0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
11600 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
11610 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
11620 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  me()] API if des
11630 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
11640 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70   for "?NNN".** p
11650 61 72 61 6d 65 74 65 73 20 69 73 20 74 68 65 20  arametes is the 
11660 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
11670 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
11680 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
11690 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
116a0 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
116b0 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
116c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
116d0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
116e0 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72  9)..** See <a hr
116f0 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22  ef="limits.html"
11700 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e  >limits.html</a>
11710 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
11720 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
11730 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
11740 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
11750 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
11760 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
11770 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72  ** In those.** r
11780 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
11790 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
117a0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
117b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
117c0 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20  bytes.** in the 
117d0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
117e0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
117f0 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
11800 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
11810 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  .** string, not 
11820 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
11830 61 72 61 63 74 65 72 73 2e 20 20 54 68 65 20 6e  aracters.  The n
11840 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
11850 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  s does not inclu
11860 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  de the zero-term
11870 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
11880 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  d of strings..**
11890 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
118a0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
118b0 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
118c0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
118d0 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  s.** number of b
118e0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
118f0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
11900 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
11910 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
11920 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
11930 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
11940 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
11950 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
11960 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
11970 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
11980 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
11990 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20  BLOB or.** text 
119a0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
119b0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
119c0 74 2e 20 20 49 66 20 74 68 65 20 66 69 66 74 68  t.  If the fifth
119d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
119e0 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 61 6c 75  .** special valu
119f0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
11a00 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72  ], then the libr
11a10 61 72 79 20 61 73 73 75 6d 65 73 20 74 68 61 74  ary assumes that
11a20 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   the information
11a30 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74 69 63  .** is in static
11a40 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
11a50 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
11a60 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
11a70 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69 66 74    If the.** fift
11a80 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
11a90 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
11aa0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
11ab0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  n SQLite makes i
11ac0 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74  ts.** own privat
11ad0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
11ae0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
11af0 62 65 66 6f 72 65 20 74 68 65 20 73 71 6c 69 74  before the sqlit
11b00 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72  e3_bind_*().** r
11b10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
11b20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11b30 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
11b40 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
11b50 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
11b60 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   n that.** is fi
11b70 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e  lled with zeros.
11b80 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
11b90 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
11ba0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
11bb0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
11bc0 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20  o hold it size) 
11bd0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
11be0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
11bf0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
11c00 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
11c10 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73  as place-holders
11c20 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
11c30 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
11c40 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
11c50 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
11c60 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
11c70 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20  ement BLOB I/O] 
11c80 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11c90 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
11ca0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
11cb0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
11cc0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
11cd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
11ce0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
11cf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
11d00 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
11d10 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
11d20 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
11d30 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
11d40 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
11d50 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
11d60 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
11d70 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
11d80 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
11d90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
11da0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
11db0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
11dc0 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
11dd0 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
11de0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
11df0 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
11e00 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
11e10 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
11e20 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
11e30 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
11e40 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
11e50 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61  ned if malloc fa
11e60 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
11e70 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74 75 72  MISUSE] is retur
11e80 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
11e90 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
11ea0 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a   on a virtual.**
11eb0 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
11ec0 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
11ed0 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
11ee0 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
11ef0 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ized..*/.int sql
11f00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
11f10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11f20 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
11f30 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
11f40 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
11f50 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
11f60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
11f70 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
11f80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
11f90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
11fa0 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
11fb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
11fc0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
11fd0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
11fe0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
11ff0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
12000 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
12010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
12020 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
12030 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
12040 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
12050 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
12060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12070 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
12080 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
12090 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
120a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
120b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
120c0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
120d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
120e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
120f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
12100 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
12110 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
12120 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
12130 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
12140 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65  Of Host Paramete
12150 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  rs.**.** Return 
12160 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f 73 74  the largest host
12170 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 65 78   parameter index
12180 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d 70 69   in the precompi
12190 6c 65 64 20 73 74 61 74 65 6d 65 6e 74 20 67 69  led statement gi
121a0 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65 20 61 72  ven.** as the ar
121b0 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e 20 74 68  gument.  When th
121c0 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  e host parameter
121d0 73 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72  s are of the for
121e0 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a  ms like ":AAA".*
121f0 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65 6e 20 74  * or "?", then t
12200 68 65 79 20 61 72 65 20 61 73 73 69 67 6e 65 64  hey are assigned
12210 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72   sequential incr
12220 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62  easing numbers b
12230 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68  eginning.** with
12240 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c   one, so the val
12250 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
12260 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  he number of par
12270 61 6d 65 74 65 72 73 2e 20 20 48 6f 77 65 76 65  ameters.  Howeve
12280 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61 6d 65  r.** if the same
12290 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
122a0 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d 75 6c  name is used mul
122b0 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65 61 63  tiple times, eac
122c0 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20  h occurrance.** 
122d0 69 73 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  is given the sam
122e0 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74 68 65  e number, so the
122f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
12300 69 6e 20 74 68 61 74 20 63 61 73 65 20 69 73 20  in that case is 
12310 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
12320 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70 61 72   unique host par
12330 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20 20 49  ameter names.  I
12340 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  f host parameter
12350 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
12360 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75 73 65 64  NNN".** are used
12370 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61   (where NNN is a
12380 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65 6e 20  n integer) then 
12390 74 68 65 72 65 20 6d 69 67 68 74 20 62 65 20 67  there might be g
123a0 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75  aps in the.** nu
123b0 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68 65 20  mbering and the 
123c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
123d0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
123e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
123f0 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72   the.** host par
12400 61 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20  ameter with the 
12410 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 76 61  largest index va
12420 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  lue..**.** The p
12430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12440 74 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 5b 73  t must not be [s
12450 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
12460 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a 20  | finalized].** 
12470 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72 6f  prior to this ro
12480 75 74 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e 67  utine returnning
12490 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68 65  .  Otherwise the
124a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
124b0 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 72  efined.** and pr
124c0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
124d0 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
124e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
124f0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
12500 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
12510 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
12520 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
12530 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  r.**.** This rou
12540 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
12550 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
12560 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 20 70  me of the n-th p
12570 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 0a 2a  arameter in a .*
12580 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
12590 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
125a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 70  ment]..** Host p
125b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
125c0 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
125d0 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22  "@AAA" or "$VVV"
125e0 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
125f0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
12600 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
12610 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
12620 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f   .** In other wo
12630 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
12640 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
12650 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  @".** is include
12660 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
12670 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
12680 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
12690 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68   "?" or "?NNN" h
126a0 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a  ave no name..**.
126b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 62 6f 75  ** The first bou
126c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  nd parameter has
126d0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
126e0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
126f0 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
12700 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
12710 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
12720 65 74 65 72 20 69 73 20 6e 61 6d 65 6c 65 73 73  eter is nameless
12730 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ,.** then NULL i
12740 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
12750 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
12760 20 69 73 20 61 6c 77 61 79 73 20 69 6e 20 74 68   is always in th
12770 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f 64  e.** UTF-8 encod
12780 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
12790 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
127a0 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  was originally s
127b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 61 73 20 55  pecified.** as U
127c0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
127d0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
127e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
127f0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
12800 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
12810 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
12820 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
12830 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
12840 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
12850 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
12860 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
12870 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ame.**.** This r
12880 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
12890 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 6f  he index of a ho
128a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  st parameter wit
128b0 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65  h the given name
128c0 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d 75  ..** The name mu
128d0 73 74 20 6d 61 74 63 68 20 65 78 61 63 74 6c 79  st match exactly
128e0 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 74  .  If no paramet
128f0 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 65  er with the give
12900 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66 6f  n name is .** fo
12910 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 20 20  und, return 0.  
12920 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20  Parameter names 
12930 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f  must be UTF8..*/
12940 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
12950 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
12960 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
12970 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
12980 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
12990 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
129a0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
129b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
129c0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
129d0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
129e0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
129f0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
12a00 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68   not.** reset th
12a10 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
12a20 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
12a30 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   on a .** [sqlit
12a40 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
12a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
12a60 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
12a70 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c   to.** reset all
12a80 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
12a90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
12aa0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
12ab0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
12ac0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
12ad0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
12ae0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
12af0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
12b00 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
12b10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
12b20 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
12b30 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
12b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
12b50 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  t | compiled SQL
12b60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69   statement]. Thi
12b70 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
12b80 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20  s 0.** if pStmt 
12b90 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  is an SQL statem
12ba0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
12bb0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
12bc0 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61  or .** example a
12bd0 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 6e  n UPDATE)..*/.in
12be0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
12bf0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
12c00 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
12c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12c20 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
12c30 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
12c40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12c50 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
12c60 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
12c70 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
12c80 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
12c90 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
12ca0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
12cb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
12cc0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
12cd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
12ce0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 38 20  inter to a UTF8 
12cf0 73 74 72 69 6e 67 20 61 6e 64 20 73 71 6c 69 74  string and sqlit
12d00 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
12d10 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
12d20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46  pointer to a UTF
12d30 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
12d40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12d50 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  is the.** [sqlit
12d60 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
12d70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
12d80 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
12d90 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
12da0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  nt..** The secon
12db0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
12dc0 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  he column number
12dd0 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
12de0 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75   column is.** nu
12df0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68  mber 0..**.** Th
12e00 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
12e10 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
12e20 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
12e30 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
12e40 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
12e50 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
12e60 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
12e70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
12e80 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
12e90 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74   next call sqlit
12ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
12eb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
12ec0 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f  mn_name16().** o
12ed0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
12ee0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
12ef0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
12f00 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
12f10 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
12f20 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
12f30 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
12f40 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
12f50 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
12f60 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
12f70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
12f80 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  eturned..*/.cons
12f90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
12fa0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
12fb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
12fc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
12fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
12fe0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
12ff0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
13000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
13010 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
13020 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
13030 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13040 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
13050 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
13060 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
13070 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
13080 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
13090 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
130a0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
130b0 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
130c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
130d0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
130e0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
130f0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
13100 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20  ither a UTF8 or 
13110 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
13120 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
13130 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
13140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
13150 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
13160 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13170 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
13180 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
13190 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
131a0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
131b0 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
131c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
131d0 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
131e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
131f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
13200 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
13210 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
13220 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
13230 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
13240 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
13250 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
13260 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
13270 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
13280 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74  ** The names ret
13290 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
132a0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
132b0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
132c0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
132d0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
132e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
132f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66  rgument to the f
13300 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69  ollowing calls i
13310 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s a .** [sqlite3
13320 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
13330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
13340 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
13350 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
13360 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
13370 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
13380 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20  rned by .** the 
13390 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
133a0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
133b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
133c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  nt..**.** If the
133d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
133e0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
133f0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
13400 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62  ession.** or sub
13410 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
13420 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
13430 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
13440 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
13450 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68  return NULL. Oth
13460 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
13470 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65  urn the .** name
13480 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
13490 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
134a0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
134b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
134c0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
134d0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
134e0 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
134f0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
13500 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
13510 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
13520 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f  n UTF-16.** enco
13530 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
13540 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
13550 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
13560 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
13570 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
13580 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
13590 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
135a0 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
135b0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
135c0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
135d0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
135e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
135f0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
13600 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
13610 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
13620 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
13630 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
13640 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
13650 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
13660 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
13670 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
13680 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  * undefined..*/.
13690 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
136a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
136b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
136c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
136d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
136e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
136f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
13700 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
13710 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
13720 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
13730 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
13740 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
13750 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13760 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
13770 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
13780 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
13790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
137a0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
137b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
137c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
137d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
137e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
137f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
13800 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
13810 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
13820 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
13830 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
13840 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 73  arameter is a [s
13850 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f  qlite3_stmt | co
13860 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
13870 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68  ment]. .** If th
13880 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
13890 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
138a0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
138b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a  olumn of the .**
138c0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
138d0 20 73 65 74 20 20 6f 66 20 74 68 61 74 20 53 45   set  of that SE
138e0 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20  LECT is a table 
138f0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
13900 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
13910 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
13920 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
13930 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
13940 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
13950 6e 65 64 2e 20 49 66 20 74 68 65 20 4e 74 68 20  ned. If the Nth 
13960 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
13970 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
13980 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
13990 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
139a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
139b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
139c0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
139d0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
139e0 38 20 65 6e 63 6f 64 65 64 2e 20 46 6f 72 20 65  8 encoded. For e
139f0 78 61 6d 70 6c 65 2c 20 69 6e 0a 2a 2a 20 74 68  xample, in.** th
13a00 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
13a10 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
13a20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
13a30 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
13a40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
13a50 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
13a60 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
13a70 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
13a80 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
13a90 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
13aa0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
13ab0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
13ac0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
13ad0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
13ae0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
13af0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
13b00 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
13b10 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
13b20 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
13b30 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
13b40 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
13b50 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
13b60 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
13b70 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
13b80 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
13b90 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
13ba0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
13bb0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
13bc0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
13bd0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
13be0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
13bf0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
13c00 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
13c10 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
13c20 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
13c30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
13c40 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
13c50 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
13c60 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
13c70 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
13c80 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
13c90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
13ca0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
13cb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e  lite3_stmt *, in
13cc0 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t i);.const void
13cd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
13ce0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
13cf0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
13d00 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46  ./* .** CAPI3REF
13d10 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  :  Evaluate An S
13d20 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
13d30 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b 73 71 6c  ** After an [sql
13d40 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
13d50 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
13d60 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74  een prepared wit
13d70 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65  h a call.** to e
13d80 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
13d90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
13da0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13db0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f  16_v2()] or to o
13dc0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67  ne of.** the leg
13dd0 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
13de0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
13df0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
13e00 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
13e10 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69  then this functi
13e20 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  on must be calle
13e30 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
13e40 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
13e50 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  the .** statemen
13e60 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
13e70 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
13e80 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c  vior of this sql
13e90 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
13ea0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
13eb0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
13ec0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
13ed0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
13ee0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
13ef0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
13f00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
13f10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
13f20 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
13f30 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
13f40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
13f50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
13f60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
13f70 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
13f80 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
13f90 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
13fa0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
13fb0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
13fc0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
13fd0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
13fe0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
13ff0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
14000 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61  .**.** In the la
14010 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
14020 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
14030 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
14040 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a  [SQLITE_BUSY], .
14050 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
14060 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
14070 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
14080 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
14090 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
140a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
140b0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
140c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
140d0 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72  sult code].** or
140e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
140f0 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
14100 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68  esult code] migh
14110 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
14120 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  .** well..**.** 
14130 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
14140 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
14150 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
14160 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
14170 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
14180 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
14190 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
141a0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
141b0 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a  nt is a COMMIT.*
141c0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
141d0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
141e0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
141f0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
14200 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
14210 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
14220 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
14230 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72  COMMIT and occur
14240 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
14250 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
14260 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
14270 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
14280 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
14290 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
142a0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
142b0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
142c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
142d0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
142e0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
142f0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
14300 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
14310 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
14320 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
14330 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
14340 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
14350 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
14360 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
14370 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
14380 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
14390 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
143a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
143b0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
143c0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
143d0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
143e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57   .** [SQLITE_ROW
143f0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  ] is returned ea
14400 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
14410 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
14420 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73  dy.** for proces
14430 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c  sing by the call
14440 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
14450 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
14460 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
14470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
14480 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20  | column access 
14490 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
144a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
144b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
144c0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
144d0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
144e0 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ** .** [SQLITE_E
144f0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
14500 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
14510 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
14520 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
14530 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
14540 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
14550 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
14560 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
14570 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
14580 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
14590 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
145a0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
145b0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
145c0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
145d0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
145e0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
145f0 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20  de (example:.** 
14600 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
14610 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
14620 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
14630 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
14640 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
14650 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
14660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
14670 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
14680 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
14690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
146a0 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22  t].  In the "v2"
146b0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
146c0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
146d0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
146e0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
146f0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
14700 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
14710 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
14720 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
14730 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
14740 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
14750 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
14760 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
14770 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
14780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14790 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
147a0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
147b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
147c0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
147d0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a  n one that had .
147e0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
147f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
14800 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
14810 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
14820 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
14830 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
14840 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14850 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
14860 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
14870 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
14880 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
14890 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
148a0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
148b0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a  ce Alert:</b>.**
148c0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
148d0 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68  nterface, .** th
148e0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
148f0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
14900 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
14910 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51  ror code,.** [SQ
14920 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
14930 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72  lowing any error
14940 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
14950 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64  ITE_BUSY].** and
14960 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
14970 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
14980 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
14990 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
149a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
149b0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
149c0 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66  ne of the specif
149d0 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ic.** [SQLITE_ER
149e0 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ROR | result cod
149f0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
14a00 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
14a10 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
14a20 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
14a30 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
14a40 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
14a50 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
14a60 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
14a70 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
14a80 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
14a90 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
14aa0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
14ab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14ac0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
14ad0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
14ae0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
14af0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
14b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
14b10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
14b20 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
14b30 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70   the .** more sp
14b40 65 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 45  ecific [SQLITE_E
14b50 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f  RROR | result co
14b60 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
14b70 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
14b80 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
14b90 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
14ba0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
14bb0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
14bc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
14bd0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
14be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14bf0 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  REF:.**.** Retur
14c00 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
14c10 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75  values in the cu
14c20 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
14c30 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a   result set..**.
14c40 2a 2a 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  ** After a call 
14c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
14c60 28 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  ()] that returns
14c70 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
14c80 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77  his routine.** w
14c90 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
14ca0 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
14cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
14cc0 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69  _count()] functi
14cd0 6f 6e 2e 0a 2a 2a 20 41 66 74 65 72 20 5b 73 71  on..** After [sq
14ce0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
14cf0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 20 5b 53  s returned an [S
14d00 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
14d10 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a  LITE_BUSY], or.*
14d20 2a 20 61 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  * a [SQLITE_ERRO
14d30 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 2c  R | error code],
14d40 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
14d50 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
14d60 62 65 65 6e 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  been .** called 
14d70 6f 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  on the [sqlite3_
14d80 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
14d90 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74  statement] for t
14da0 68 65 20 66 69 72 73 74 20 74 69 6d 65 2c 0a 2a  he first time,.*
14db0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * this routine r
14dc0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
14dd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
14de0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
14df0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
14e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
14e10 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
14e20 70 65 73 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  pes.**.** Every 
14e30 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
14e40 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
14e50 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
14e60 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
14e70 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
14e80 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
14e90 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
14ea0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
14eb0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
14ec0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
14ed0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
14ee0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  LL.** </ul>.**.*
14ef0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
14f00 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
14f10 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
14f20 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
14f30 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
14f40 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
14f50 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
14f60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
14f70 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
14f80 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
14f90 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
14fa0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
14fb0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
14fc0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
14fd0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
14fe0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
14ff0 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a  ITE3_TEXT not.**
15000 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
15010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15020 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
15030 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
15040 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
15050 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
15060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
15070 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
15080 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
15090 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
150a0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
150b0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
150c0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
150d0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
150e0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
150f0 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75  EF: Results Valu
15100 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
15110 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
15120 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
15130 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a  rmation about.**
15140 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
15150 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
15160 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
15170 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
15180 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72  .** case the fir
15190 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
151a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
151b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
151c0 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
151d0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
151e0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74  .** evaluated (t
151f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
15200 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75  *] that was retu
15210 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  rned from .** [s
15220 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15230 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
15240 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64  ts variants) and
15250 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61  .** the second a
15260 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
15270 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
15280 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
15290 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f  ormation .** sho
152a0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
152b0 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
152c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
152d0 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20  sult set.** has 
152e0 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a  an index of 0..*
152f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
15300 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
15310 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
15320 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
15330 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68   or if the.** th
15340 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  e column index i
15350 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
15360 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
15370 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65  defined. .** The
15380 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
15390 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
153a0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
153b0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
153c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
153d0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
153e0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
153f0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
15400 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
15410 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
15420 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
15430 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  l subsequently..
15440 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
15450 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
15460 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
15470 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
15480 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
15490 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
154a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
154b0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
154c0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
154d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
154e0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
154f0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
15500 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
15510 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
15520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
15530 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15540 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
15550 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
15560 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
15570 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
15580 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
15590 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
155a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
155b0 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  efined.  .**.** 
155c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
155d0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
155e0 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  e returns .** [S
155f0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
15600 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
15610 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
15620 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
15630 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
15640 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
15650 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
15660 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
15670 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
15680 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
15690 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
156a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
156b0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
156c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
156d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
156e0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
156f0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
15700 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
15710 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
15720 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
15730 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
15740 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
15750 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
15760 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
15770 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
15780 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
15790 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
157a0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
157b0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
157c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
157d0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
157e0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
157f0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
15800 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
15810 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
15820 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
15830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15840 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74  bytes() .** rout
15850 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
15860 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
15870 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
15880 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
15890 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
158a0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
158b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
158c0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
158d0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
158e0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
158f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
15900 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
15910 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
15920 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
15930 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
15940 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
15950 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
15960 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
15970 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
15980 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
15990 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
159a0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
159b0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
159c0 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
159d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
159e0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
159f0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15a00 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
15a10 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
15a20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
15a30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
15a40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
15a50 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
15a60 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
15a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
15a80 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15aa0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
15ab0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
15ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
15ad0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
15ae0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
15af0 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61  in UTF-16 instea
15b00 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a  d of UTF-8.  .**
15b10 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
15b20 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
15b30 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
15b40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  nt..**.** These 
15b50 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
15b60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
15b70 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
15b80 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
15b90 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
15ba0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
15bb0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
15bc0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
15bd0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
15be0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
15bf0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
15c00 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
15c10 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
15c20 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
15c30 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
15c40 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
15c50 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
15c60 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
15c70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
15c80 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
15c90 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
15ca0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
15cb0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
15cc0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
15cd0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
15ce0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
15cf0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
15d00 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
15d10 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
15d20 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
15d30 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
15d40 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
15d50 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
15d60 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
15d70 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
15d80 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
15d90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
15da0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
15db0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
15dc0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
15dd0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
15de0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
15df0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
15e00 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
15e10 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
15e20 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
15e30 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
15e40 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
15e50 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
15e60 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
15e70 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
15e80 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
15e90 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
15ea0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
15eb0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
15ec0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
15ed0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
15ee0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
15ef0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
15f00 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
15f10 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
15f20 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
15f30 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
15f40 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
15f50 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
15f60 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
15f70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
15f80 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
15f90 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
15fa0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
15fb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
15fc0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
15fd0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
15fe0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
15ff0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
16000 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
16010 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
16020 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
16030 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
16040 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
16050 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
16060 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
16070 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
16080 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
16090 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
160a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
160b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
160c0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
160d0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
160e0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
160f0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
16100 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
16110 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
16120 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
16130 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
16140 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
16150 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
16160 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
16170 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
16180 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
16190 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
161a0 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
161b0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
161c0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
161d0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
161e0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
161f0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
16200 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
16210 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
16220 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
16230 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
16240 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
16250 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
16260 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
16270 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
16280 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
16290 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
162a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
162b0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
162c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
162d0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
162e0 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
162f0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
16300 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
16310 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
16320 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
16330 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
16340 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
16350 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
16360 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
16370 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
16380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16390 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
163a0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
163b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
163c0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
163d0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
163e0 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
163f0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
16400 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
16410 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
16420 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
16430 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
16440 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
16450 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
16460 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
16470 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16480 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
16490 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
164a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
164b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
164c0 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
164d0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
164e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
164f0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
16500 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
16510 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
16520 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
16530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
16540 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
16550 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
16560 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
16570 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
16580 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
16590 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
165a0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
165b0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
165c0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
165d0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
165e0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
165f0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
16600 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
16610 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
16620 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
16630 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
16640 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
16650 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
16660 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
16670 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
16680 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
16690 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
166a0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
166b0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
166c0 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
166d0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
166e0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
166f0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
16700 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
16710 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
16720 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
16730 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
16740 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
16750 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
16760 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
16770 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
16780 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
16790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
167a0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
167b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
167c0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
167d0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
167e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
167f0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
16800 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
16810 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
16820 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
16830 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
16840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
16850 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
16860 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
16870 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
16880 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
16890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
168a0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
168b0 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
168c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
168d0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
168e0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
168f0 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
16900 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
16910 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
16920 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16930 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
16940 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
16950 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
16960 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
16970 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
16980 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
16990 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
169a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
169b0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
169c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
169d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
169e0 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
169f0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
16a00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
16a10 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
16a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16a30 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
16a40 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
16a50 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
16a60 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
16a70 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
16a80 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
16a90 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
16aa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
16ab0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
16ac0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
16ad0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
16ae0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
16af0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
16b00 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
16b10 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
16b20 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
16b30 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
16b40 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
16b50 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
16b60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
16b70 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
16b80 69 74 65 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  ite_column_text(
16b90 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
16ba0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
16bb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
16bc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16bd0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
16be0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
16bf0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
16c00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
16c10 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
16c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
16c30 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16c40 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
16c50 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
16c60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
16c70 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
16c80 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
16c90 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
16ca0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
16cb0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
16cc0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
16cd0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e  E_NOMEM]..*/.con
16ce0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
16cf0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
16d00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16d10 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
16d20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
16d40 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
16d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
16d60 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
16d70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
16d80 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
16d90 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
16da0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
16db0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
16dc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
16dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16de0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
16df0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
16e00 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
16e10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
16e20 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
16e30 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
16e40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
16e50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
16e60 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
16e70 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
16e80 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
16e90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
16ea0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
16eb0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
16ec0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
16ed0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
16ee0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
16ef0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
16f00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
16f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16f20 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
16f30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
16f40 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
16f50 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
16f60 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
16f70 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
16f80 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e a .** [sqlite3
16f90 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
16fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
16fb0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
16fc0 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
16fd0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
16fe0 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
16ff0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
17000 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
17010 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
17020 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
17030 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
17040 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
17050 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
17060 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
17070 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
17080 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
17090 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
170a0 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
170b0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
170c0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
170d0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
170e0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
170f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76  sqlite3_stmt | v
17100 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e  irtual machine].
17110 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
17120 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
17130 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65   .** completed e
17140 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
17150 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
17160 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
17170 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
17180 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
17190 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53  n interrupt.  (S
171a0 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  ee [sqlite3_inte
171b0 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49  rrupt()].) .** I
171c0 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
171d0 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
171e0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
171f0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c  tions cancelled,
17200 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20    .** depending 
17210 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
17220 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a  nces, and the .*
17230 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
17240 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72  | result code] r
17250 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
17260 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
17270 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
17280 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
17290 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
172a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
172b0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
172c0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
172d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
172e0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
172f0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
17300 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71   reset a .** [sq
17310 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
17320 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17330 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  ent] object..** 
17340 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69  back to it's ini
17350 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
17360 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
17370 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
17380 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
17390 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
173a0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
173b0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
173c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
173d0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
173e0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
173f0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
17400 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
17410 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
17420 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
17430 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73  ndings..*/.int s
17440 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
17450 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
17460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17470 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
17480 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
17490 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ions.**.** The f
174a0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
174b0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
174c0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
174d0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
174e0 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65  es.** or to rede
174f0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
17500 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  r of existing SQ
17510 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
17520 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a  ggregates.  The.
17530 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e  ** difference on
17540 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74  ly between the t
17550 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
17560 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
17570 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
17580 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
17590 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
175a0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
175b0 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  n UTF-8 for.** s
175c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
175d0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
175e0 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  -16 for sqlite3_
175f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
17600 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
17610 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20   the [sqlite3 | 
17630 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
17640 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a   that holds the.
17650 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
17660 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20  or aggregate is 
17670 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72  to be added or r
17680 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73  edefined. If a s
17690 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  ingle.** program
176a0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
176b0 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  one database han
176c0 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  dle internally, 
176d0 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
176e0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
176f0 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  tes must be adde
17700 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
17710 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  o each database.
17720 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  ** handle with w
17730 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
17740 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
17750 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17760 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
17770 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
17780 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
17790 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
177a0 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
177b0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
177c0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
177d0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
177e0 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
177f0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
17800 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
17810 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
17820 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
17830 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
17840 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
17850 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
17860 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
17870 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
17880 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
17890 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
178a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
178b0 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
178c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
178d0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
178e0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
178f0 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
17900 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
17910 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17920 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
17930 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
17940 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
17950 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
17960 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
17970 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
17980 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
17990 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
179a0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
179b0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
179c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
179d0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
179e0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
179f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
17a00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
17a10 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
17a20 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
17a30 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
17a40 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
17a50 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
17a60 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
17a70 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
17a80 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
17a90 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
17aa0 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
17ab0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
17ac0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
17ad0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
17ae0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
17af0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
17b00 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
17b10 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
17b20 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
17b30 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
17b40 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
17b50 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
17b60 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
17b70 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
17b80 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
17b90 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
17ba0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
17bb0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
17bc0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
17bd0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
17be0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
17bf0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
17c00 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
17c10 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
17c20 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
17c30 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
17c40 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
17c50 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
17c60 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
17c70 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
17c80 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
17c90 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
17ca0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
17cb0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
17cc0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
17cd0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
17ce0 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
17cf0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
17d00 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
17d10 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
17d20 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
17d30 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
17d40 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
17d50 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
17d60 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
17d70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
17d80 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
17d90 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
17da0 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
17db0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
17dc0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
17dd0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
17de0 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
17df0 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
17e00 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
17e10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
17e20 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
17e30 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
17e40 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
17e50 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
17e60 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
17e70 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
17e80 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
17e90 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
17ea0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
17eb0 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
17ec0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
17ed0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
17ee0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
17ef0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
17f00 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
17f10 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
17f20 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
17f30 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
17f40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
17f50 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
17f60 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
17f70 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
17f80 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
17f90 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
17fa0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
17fb0 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
17fc0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
17fd0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
17fe0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
17ff0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
18000 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
18010 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
18020 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
18030 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69  on is used..*/.i
18040 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18050 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
18060 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74  lite3 *,.  const
18070 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
18080 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
18090 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
180a0 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69  ,.  void*,.  voi
180b0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
180c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
180d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
180e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
180f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
18100 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
18110 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
18120 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
18130 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
18140 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18150 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
18160 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
18170 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
18180 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
18190 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
181a0 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  p,.  void*,.  vo
181b0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
181c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
181d0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
181e0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
181f0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
18200 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
18210 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
18220 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
18230 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
18240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18250 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
18260 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
18270 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
18280 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
18290 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
182a0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
182b0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
182c0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
182d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
182e0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
182f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18300 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
18310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18320 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
18330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18340 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
18350 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
18360 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
18370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
18380 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
18390 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
183a0 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
183b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
183c0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
183d0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
183e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
183f0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
18400 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
18410 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
18420 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
18430 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
18440 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
18450 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
18460 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
18470 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
18480 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
18490 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
184a0 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
184b0 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
184c0 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
184d0 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
184e0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
184f0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
18500 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
18510 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
18520 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
18530 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
18540 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
18550 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
18560 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
18570 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
18580 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
18590 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
185a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
185b0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
185c0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
185d0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
185e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
185f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
18600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
18610 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
18620 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
18630 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
18640 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
18650 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
18660 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
18670 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
18680 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
18690 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
186a0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
186b0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
186c0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
186d0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
186e0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
186f0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
18700 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
18710 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
18720 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
18730 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
18740 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
18750 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
18760 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
18770 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
18780 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18790 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
187a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
187b0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
187c0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
187d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
187e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
187f0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
18800 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
18810 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
18820 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
18830 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
18840 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
18850 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
18860 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
18870 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
18880 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
18890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
188a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
188b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
188c0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
188d0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
188e0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
188f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
18900 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18910 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
18920 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
18930 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
18940 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
18950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
18960 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
18970 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
18980 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
18990 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
189a0 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
189b0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
189c0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
189d0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
189e0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
189f0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
18a00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
18a10 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
18a20 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
18a30 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
18a40 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
18a50 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
18a60 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
18a70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
18a80 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
18a90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
18aa0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
18ab0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
18ac0 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
18ad0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
18ae0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
18af0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
18b00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
18b10 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
18b20 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
18b30 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
18b40 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
18b50 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
18b60 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
18b70 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
18b80 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
18b90 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
18ba0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
18bb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
18bc0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
18bd0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
18be0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
18bf0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
18c00 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64  in order.** word
18c10 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
18c20 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72  s original a str
18c30 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
18c40 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
18c50 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65   then it is done
18c60 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
18c70 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
18c80 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
18c90 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
18ca0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
18cb0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
18cc0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
18cd0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
18ce0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
18cf0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
18d00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
18d10 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
18d20 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
18d30 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
18d40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
18d50 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
18d60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
18d70 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
18d80 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
18d90 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
18da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
18db0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
18dc0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
18dd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
18de0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
18df0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
18e00 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a  text16()].  .**.
18e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18e20 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
18e30 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
18e40 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
18e50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
18e60 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73  t supplied the s
18e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61  qlite3_value* pa
18e80 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c  rameters..** Or,
18e90 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
18ea0 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20  value* argument 
18eb0 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  comes from the [
18ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
18ed0 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  alue()].** inter
18ee0 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65  face, then these
18ef0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
18f00 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
18f10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a  the same thread.
18f20 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c  ** that ran [sql
18f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
18f40 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  e()]..*/.const v
18f50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
18f60 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
18f70 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
18f80 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
18f90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
18fa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
18fb0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
18fc0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
18fd0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
18fe0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
18ff0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
19000 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
19010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
19020 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
19030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
19040 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
19050 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
19060 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
19070 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
19080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
19090 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
190a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
190b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
190c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
190d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
190e0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
190f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
19100 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19110 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
19120 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19130 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
19140 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19150 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19160 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
19170 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
19180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19190 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
191a0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
191b0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  t.**.** The impl
191c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
191d0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
191e0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
191f0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
19200 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
19210 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
19220 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20  eir state.  The 
19230 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
19240 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61  routine.** is ca
19250 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
19260 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
19270 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65   a new structure
19280 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a   of size nBytes.
19290 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c  ** is allocated,
192a0 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74   zeroed, and ret
192b0 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65  urned.  On subse
192c0 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72  quent calls (for
192d0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67   the.** same agg
192e0 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29  regate instance)
192f0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
19300 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
19310 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
19320 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
19330 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
19340 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
19350 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
19360 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  data..**.** The 
19370 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64  buffer allocated
19380 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
19390 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  tically by SQLit
193a0 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65  e whan the aggre
193b0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
193c0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
193d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
193e0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
193f0 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
19400 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
19410 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
19420 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
19430 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
19440 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
19450 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
19460 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
19470 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
19480 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19490 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
194a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
194b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
194c0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
194d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
194e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
194f0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
19500 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
19510 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
19520 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
19530 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
19540 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
19550 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
19560 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61  *.** The pUserDa
19570 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ta parameter to 
19580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
19590 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
195a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
195b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
195c0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  6()] routines.**
195d0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
195e0 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73  r user functions
195f0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
19600 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
19610 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75  tation of the fu
19620 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69  nction using thi
19630 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s call..**.** Th
19640 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
19650 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
19660 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
19670 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
19680 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
19690 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
196a0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
196b0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
196c0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
196d0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
196e0 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
196f0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
19700 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
19710 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
19720 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
19730 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
19740 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
19750 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
19760 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
19770 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
19780 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
19790 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
197a0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
197b0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
197c0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
197d0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
197e0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
197f0 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
19800 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
19810 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
19820 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
19830 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
19840 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
19850 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
19860 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
19870 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
19880 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
19890 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
198a0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
198b0 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
198c0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
198d0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
198e0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
198f0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
19900 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
19910 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
19920 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
19930 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
19940 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
19950 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
19960 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
19970 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
19980 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
19990 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
199a0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
199b0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
199c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
199d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
199e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
199f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
19a00 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
19a10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
19a20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  Nth argument val
19a30 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ue to the curren
19a40 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  t SQL function.*
19a50 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20  * call, where N 
19a60 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19a70 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d  rameter. If no m
19a80 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65  eta-data has bee
19a90 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61  n set for.** tha
19aa0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20  t value, then a 
19ab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
19ac0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
19ae0 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65  auxdata() is use
19af0 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d  d to associate m
19b00 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e  eta-data with an
19b10 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
19b20 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74   argument. The t
19b30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
19b40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
19b50 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
19b60 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64  to be associated
19b70 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73   with the Nth us
19b80 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  er function argu
19b90 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20  ment value. The 
19ba0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
19bb0 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20  ter specifies a 
19bc0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
19bd0 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f  will be called o
19be0 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64  n the meta-.** d
19bf0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72  ata pointer to r
19c00 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69  elease it when i
19c10 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
19c20 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20  equired. If the 
19c30 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69  .** destructor i
19c40 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f  s NULL, it is no
19c50 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  t invoked..**.**
19c60 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
19c70 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
19c80 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
19c90 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
19ca0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
19cb0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
19cc0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19cd0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
19ce0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
19cf0 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
19d00 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
19d10 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
19d20 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
19d30 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
19d40 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
19d50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
19d60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
19d70 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
19d80 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
19d90 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
19da0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
19db0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
19dc0 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  text*, int, void
19dd0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
19de0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
19df0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
19e00 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
19e10 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
19e20 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
19e30 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
19e40 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74  lue for the dest
19e50 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
19e60 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
19e70 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
19e80 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
19e90 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
19ea0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
19eb0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
19ec0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
19ed0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
19ee0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
19ef0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
19f00 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
19f10 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
19f20 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
19f30 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
19f40 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a  troyed.  The .**
19f50 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
19f60 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
19f70 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
19f80 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
19f90 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
19fa0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
19fb0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
19fc0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
19fd0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
19fe0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
19ff0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
1a000 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
1a010 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
1a020 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
1a030 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
1a040 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
1a050 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
1a060 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
1a070 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
1a080 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
1a090 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
1a0a0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
1a0b0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
1a0c0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
1a0d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1a0e0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
1a0f0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1a100 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
1a110 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
1a120 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
1a130 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
1a140 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a150 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
1a160 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
1a170 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
1a180 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
1a190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
1a1a0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
1a1b0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
1a1c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1a1d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
1a1e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
1a1f0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
1a200 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1a210 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
1a220 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
1a230 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
1a240 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
1a250 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
1a260 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
1a270 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
1a280 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
1a290 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
1a2a0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
1a2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
1a2c0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
1a2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1a2e0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1a2f0 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
1a300 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
1a310 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
1a320 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
1a330 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a340 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
1a350 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1a360 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
1a370 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
1a380 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
1a390 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
1a3a0 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  xception.  The.*
1a3b0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  * parameter to s
1a3c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a3d0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
1a3e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1a3f0 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74  ).** is the text
1a400 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
1a410 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sage..**.** The 
1a420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
1a430 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68  oobig() cause th
1a440 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
1a450 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  mentation.** to 
1a460 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20  throw and error 
1a470 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
1a480 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
1a490 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
1a4a0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
1a4b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1a4c0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1a4d0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
1a4e0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
1a4f0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1a500 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
1a510 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
1a520 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
1a530 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  r..*/.void sqlit
1a540 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
1a550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a560 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1a570 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1a580 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1a590 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
1a5a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1a5b0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
1a5c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a5d0 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
1a5e0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
1a5f0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1a600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1a610 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
1a620 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1a630 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
1a640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1a650 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
1a660 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1a670 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1a680 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
1a690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1a6a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a6b0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
1a6c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
1a6d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1a6e0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
1a6f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1a700 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
1a710 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1a720 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
1a730 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1a740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1a750 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1a760 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
1a770 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1a780 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1a790 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1a7a0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1a7b0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1a7c0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1a7d0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1a7e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1a7f0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
1a800 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
1a810 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
1a820 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1a830 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1a840 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
1a850 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1a860 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
1a870 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1a880 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1a890 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
1a8a0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
1a8b0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
1a8c0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
1a8d0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
1a8e0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
1a8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1a900 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
1a910 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
1a920 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1a930 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
1a940 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
1a950 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
1a960 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20  e.** [sqlite3*] 
1a970 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64  handle specified
1a980 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
1a990 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54  gument. .**.** T
1a9a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1a9b0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1a9c0 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
1a9d0 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
1a9e0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
1a9f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1aa00 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
1aa10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1aa20 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
1aa30 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
1aa40 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
1aa50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1aa60 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  .  In all cases.
1aa70 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
1aa80 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
1aa90 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1aaa0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
1aab0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1aac0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
1aad0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
1aae0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
1aaf0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
1ab00 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
1ab10 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
1ab20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
1ab30 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
1ab40 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
1ab50 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
1ab60 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
1ab70 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
1ab80 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
1ab90 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
1aba0 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
1abb0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1abc0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
1abd0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
1abe0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
1abf0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
1ac00 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
1ac10 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
1ac20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
1ac30 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
1ac40 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
1ac50 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
1ac60 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
1ac70 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 20  ll it anymore). 
1ac80 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75 73  Each time the us
1ac90 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66  er.** supplied f
1aca0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
1acb0 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
1acc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1acd0 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a  oid* passed as.*
1ace0 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  * the fourth arg
1acf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ad00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1ad10 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  n() or.** sqlite
1ad20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1ad30 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69  on16() as its fi
1ad40 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1ad50 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  *.** The remaini
1ad60 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
1ad70 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
1ad80 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
1ad90 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
1ada0 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
1adb0 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61 74  y a [length, dat
1adc0 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a] pair and enco
1add0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
1ade0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
1adf0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
1ae00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
1ae10 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
1ae20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
1ae30 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 20  registered. The 
1ae40 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68 6f  user routine sho
1ae50 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61 74  uld return negat
1ae60 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73  ive, zero or pos
1ae70 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20  itive if.** the 
1ae80 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
1ae90 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
1aea0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
1aeb0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a  than the second.
1aec0 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  ** string. i.e. 
1aed0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
1aee0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
1aef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1af00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
1af10 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1af20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
1af30 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61  ().** excapt tha
1af40 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
1af50 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
1af60 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
1af70 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
1af80 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
1af90 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
1afa0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
1afb0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
1afc0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
1afd0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
1afe0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1aff0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
1b000 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
1b010 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b020 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c 61  ion_v2().  Colla
1b030 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
1b040 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79  yed when.** they
1b050 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
1b060 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
1b070 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
1b080 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
1b090 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  ns.** or when th
1b0a0 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74  e [sqlite3*] dat
1b0b0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
1b0c0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
1b0d0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
1b0e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b0f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1b100 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  on_v2() interfac
1b110 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
1b120 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 74  l and.** subject
1b130 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1b140 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20  ture releases.  
1b150 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61 74  The other collat
1b160 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a 20  ion creation.** 
1b170 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 74  functions are st
1b180 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  able..*/.int sql
1b190 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
1b1a0 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
1b1b0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
1b1c0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
1b1d0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
1b1e0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
1b1f0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
1b200 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
1b210 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
1b220 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1b230 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
1b240 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
1b250 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1b260 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
1b270 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
1b280 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
1b290 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1b2a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
1b2b0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
1b2c0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
1b2d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
1b2e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
1b2f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1b300 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1b310 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
1b320 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
1b330 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
1b340 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1b350 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1b360 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
1b370 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
1b380 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
1b390 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  backs.**.** To a
1b3a0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
1b3b0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
1b3c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1b3d0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
1b3e0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
1b3f0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
1b400 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
1b410 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
1b420 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
1b430 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
1b440 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
1b450 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
1b460 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1b470 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
1b480 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
1b490 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
1b4a0 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
1b4b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
1b4c0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
1b4d0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
1b4e0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
1b4f0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
1b500 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
1b510 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
1b520 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 49  oded in UTF-8. I
1b530 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
1b540 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
1b550 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65  s used, the name
1b560 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  s.** are passed 
1b570 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
1b580 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
1b590 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74   order. A call t
1b5a0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
1b5b0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
1b5c0 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
1b5d0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
1b5e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1b5f0 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
1b600 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
1b610 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
1b620 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
1b630 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1b640 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
1b650 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
1b660 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1b670 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 63  ded16(). The sec
1b680 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1b690 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1b6a0 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 72  handle. The thir
1b6b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
1b6c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
1b6d0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
1b6e0 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  6BE], or.** [SQL
1b6f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
1b700 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
1b710 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
1b720 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
1b730 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
1b740 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
1b750 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
1b760 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
1b770 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
1b780 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
1b790 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  equence..**.** T
1b7a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1b7b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
1b7c0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
1b7d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
1b7e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1b7f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
1b800 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1b810 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
1b820 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
1b830 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1b840 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
1b850 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1b860 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
1b870 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
1b880 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
1b890 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
1b8a0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
1b8b0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
1b8c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1b8d0 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
1b8e0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
1b8f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
1b900 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
1b910 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
1b920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
1b930 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
1b940 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
1b950 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
1b960 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
1b970 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
1b980 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
1b990 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
1b9a0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
1b9b0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
1b9c0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
1b9d0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
1b9e0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
1b9f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
1ba00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1ba10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ba20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
1ba30 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
1ba40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
1ba50 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
1ba60 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
1ba70 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
1ba80 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
1ba90 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
1baa0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
1bab0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
1bac0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
1bad0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
1bae0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
1baf0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
1bb00 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1bb10 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
1bb20 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1bb30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1bb40 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1bb50 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1bb60 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1bb70 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1bb80 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
1bb90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1bba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1bbb0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
1bbc0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
1bbd0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
1bbe0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
1bbf0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
1bc00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bc10 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63  F:  Suspend Exec
1bc20 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
1bc30 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  t Time.**.** Thi
1bc40 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1bc50 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
1bc60 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
1bc70 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 6e  execution.** a n
1bc80 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
1bc90 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
1bca0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
1bcb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
1bcc0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1bcd0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
1bce0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
1bcf0 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65  with .** millise
1bd00 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
1bd10 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
1bd20 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
1bd30 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68  ded up to .** th
1bd40 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
1bd50 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
1bd60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1bd70 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a  sleep actually .
1bd80 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
1bd90 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
1bda0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
1bdb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ed..**.** SQLite
1bdc0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
1bdd0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
1bde0 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
1bdf0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
1be00 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1be10 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1be20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1be30 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
1be40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e  .** CAPI3REF:  N
1be50 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
1be60 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
1be70 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
1be80 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
1be90 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
1bea0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
1beb0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
1bec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
1bed0 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72  older (a.ka. dir
1bee0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
1bef0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
1bf00 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
1bf10 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
1bf20 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
1bf30 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
1bf40 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
1bf50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
1bf60 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20  hen SQLite does 
1bf70 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
1bf80 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70  appropriate temp
1bf90 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69  orary.** file di
1bfa0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 4f  rectory..**.** O
1bfb0 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  nce [sqlite3_ope
1bfc0 6e 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  n()] has been ca
1bfd0 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e 67 20 74  lled, changing t
1bfe0 68 69 73 20 76 61 72 69 61 62 6c 65 20 77 69 6c  his variable wil
1bff0 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61 74 65 20  l.** invalidate 
1c000 74 68 65 20 63 75 72 72 65 6e 74 20 74 65 6d 70  the current temp
1c010 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 2c 20  orary database, 
1c020 69 66 20 61 6e 79 2e 20 20 47 65 6e 65 72 61 6c  if any.  General
1c030 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a 20  ly speaking,.** 
1c040 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  it is not safe t
1c050 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 72 6f  o invoke this ro
1c060 75 74 69 6e 65 20 61 66 74 65 72 20 5b 73 71 6c  utine after [sql
1c070 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73  ite3_open()] has
1c080 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  .** been called.
1c090 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1c0a0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
1c0b0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
1c0c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c0d0 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66    Test To See If
1c0e0 20 54 68 65 20 44 61 74 61 62 73 65 20 49 73 20   The Databse Is 
1c0f0 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
1c100 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74  ode.**.** Test t
1c110 6f 20 73 65 65 20 77 68 65 74 68 65 72 20 6f 72  o see whether or
1c120 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62 61 73   not the databas
1c130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1c140 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a  in autocommit.**
1c150 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 6e 20 54   mode.  Return T
1c160 52 55 45 20 69 66 20 69 74 20 69 73 20 61 6e 64  RUE if it is and
1c170 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20   FALSE if not.  
1c180 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
1c190 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61  is on.** by defa
1c1a0 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ult.  Autocommit
1c1b0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1c1c0 61 20 42 45 47 49 4e 20 73 74 61 74 65 6d 65 6e  a BEGIN statemen
1c1d0 74 20 61 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a  t and reenabled.
1c1e0 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 74 20 43  ** by the next C
1c1f0 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43  OMMIT or ROLLBAC
1c200 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  K..**.** If anot
1c210 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
1c220 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
1c230 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
1c240 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
1c250 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
1c260 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
1c270 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
1c280 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
1c290 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
1c2a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1c2b0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
1c2c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c2d0 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65  I3REF:  Find The
1c2e0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
1c2f0 20 41 73 73 6f 63 69 61 74 65 64 20 57 69 74 68   Associated With
1c300 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
1c310 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75  ement.**.** Retu
1c320 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  rn the [sqlite3*
1c330 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
1c340 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20  e to which a.** 
1c350 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
1c360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c370 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20  nt] belongs..** 
1c380 54 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  This is the same
1c390 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1c3a0 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65   that was.** the
1c3b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1c3c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1c3d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c3e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
1c3f0 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
1c400 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  o create the sta
1c410 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
1c420 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
1c430 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
1c440 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
1c450 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
1c460 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
1c470 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
1c480 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
1c490 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  backs.**.** Thes
1c4a0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  e routines.** re
1c4b0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1c4c0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20  functions to be 
1c4d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
1c4e0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a   a transaction.*
1c4f0 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f  * is committed o
1c500 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20  r rolled back.  
1c510 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
1c520 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
1c530 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
1c540 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
1c550 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
1c560 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
1c570 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
1c580 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
1c590 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
1c5a0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
1c5b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
1c5c0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
1c5d0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
1c5e0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
1c5f0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
1c600 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72  turned..** Other
1c610 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
1c620 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
1c630 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
1c640 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
1c650 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
1c660 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
1c670 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
1c680 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
1c690 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
1c6a0 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65  e been .** rolle
1c6b0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
1c6c0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
1c6d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
1c6e0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
1c6f0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
1c700 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
1c710 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
1c720 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a   to occur. The .
1c730 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ** callback is n
1c740 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
1c750 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
1c760 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
1c770 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61  led.** back beca
1c780 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
1c790 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1c7a0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1c7b0 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e  se are experimen
1c7c0 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
1c7d0 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  nd are subject t
1c7e0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69  o change..*/.voi
1c7f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
1c800 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
1c810 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1c820 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
1c830 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
1c840 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
1c850 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
1c860 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c870 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
1c880 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
1c890 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1c8a0 20 52 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c   Register a call
1c8b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1c8c0 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
1c8d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
1c8e0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1c8f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1c900 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
1c910 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
1c920 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
1c930 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
1c940 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
1c950 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
1c960 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
1c970 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61  ction for the sa
1c980 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  me .** database 
1c990 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
1c9a0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
1c9b0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1c9c0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
1c9d0 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
1c9e0 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
1c9f0 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64  a .** row is upd
1ca00 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
1ca10 72 20 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66  r deleted. The f
1ca20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1ca30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1ca40 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68  .** a copy of th
1ca50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1ca60 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
1ca70 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73  te_hook(). The s
1ca80 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
1ca90 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
1caa0 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53  ne of SQLITE_INS
1cab0 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45  ERT, SQLITE_DELE
1cac0 54 45 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44  TE or SQLITE_UPD
1cad0 41 54 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a  ATE, depending.*
1cae0 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  * on the operati
1caf0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
1cb00 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
1cb10 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74  e invoked. The t
1cb20 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
1cb30 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
1cb40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
1cb50 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
1cb60 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
1cb70 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
1cb80 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
1cb90 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54   affected row. T
1cba0 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
1cbb0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
1cbc0 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
1cbd0 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20  the row. In the 
1cbe0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
1cbf0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72  e, this is the r
1cc00 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74  owid after .** t
1cc10 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
1cc20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
1cc30 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
1cc40 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
1cc50 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
1cc60 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
1cc70 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
1cc80 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
1cc90 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
1cca0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
1ccb0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
1ccc0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1ccd0 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
1cce0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
1ccf0 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20  d..** Otherwise 
1cd00 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
1cd10 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1cd20 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
1cd30 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
1cd40 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
1cd50 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
1cd60 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
1cd70 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
1cd80 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
1cd90 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65  API3REF:  Enable
1cda0 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
1cdb0 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
1cdc0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1cdd0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
1cde0 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e  ables the sharin
1cdf0 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
1ce00 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73  e cache.** and s
1ce10 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63  chema data struc
1ce20 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f  tures between co
1ce30 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65  nnections to the
1ce40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a   same database..
1ce50 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  ** Sharing is en
1ce60 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
1ce70 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e  ument is true an
1ce80 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
1ce90 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  e argument.** is
1cea0 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65   false..**.** Be
1ceb0 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74  ginning in SQLit
1cec0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
1ced0 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   cache sharing i
1cee0 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
1cef0 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
1cf00 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
1cf10 20 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69    In prior versi
1cf20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73  ons of SQLite, s
1cf30 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e  haring was.** en
1cf40 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
1cf50 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
1cf60 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
1cf70 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
1cf80 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
1cf90 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
1cfa0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
1cfb0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
1cfc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1cfd0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1cfe0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
1cff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d000 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
1d010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d020 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
1d030 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
1d040 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e  e that was.** in
1d050 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
1d060 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
1d070 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
1d080 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
1d090 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
1d0a0 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
1d0b0 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
1d0c0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
1d0d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
1d0e0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 41 50 49  ate_module() API
1d0f0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
1d100 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
1d110 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
1d120 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
1d130 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1d140 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
1d150 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
1d160 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65  d cache was.** e
1d170 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1d180 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
1d190 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52    An [SQLITE_ERR
1d1a0 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
1d1b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1d1c0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
1d1d0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
1d1e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1d1f0 61 75 6c 74 20 66 6f 72 20 62 61 63 6b 77 61 72  ault for backwar
1d200 64 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  d compatibility.
1d210 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d220 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1d230 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
1d240 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65   CAPI3REF:  Atte
1d250 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
1d260 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74   Memory.**.** At
1d270 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 4e 20  tempt to free N 
1d280 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
1d290 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
1d2a0 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
1d2b0 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  al.** memory all
1d2c0 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
1d2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
1d2e0 62 72 61 72 79 20 28 65 78 61 6d 70 6c 65 3a 20  brary (example: 
1d2f0 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20  memory .** used 
1d300 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
1d310 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  e pages to impro
1d320 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e  ve performance).
1d330 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
1d340 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 61  tion is not a pa
1d350 72 74 20 6f 66 20 73 74 61 6e 64 61 72 64 20 62  rt of standard b
1d360 75 69 6c 64 73 2e 20 20 49 74 20 69 73 20 6f 6e  uilds.  It is on
1d370 6c 79 20 63 72 65 61 74 65 64 0a 2a 2a 20 69 66  ly created.** if
1d380 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1d390 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
1d3a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
1d3b0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6d 61 63  Y_MANAGEMENT mac
1d3c0 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ro..*/.int sqlit
1d3d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
1d3e0 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
1d3f0 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65  API3REF:  Impose
1d400 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
1d410 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50 6c 61 63   Size.**.** Plac
1d420 65 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  e a "soft" limit
1d430 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
1d440 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
1d450 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
1d460 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ted.** by SQLite
1d470 2e 20 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  .  If an interna
1d480 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
1d490 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68  requested .** th
1d4a0 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  at would exceed 
1d4b0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6c 69  the specified li
1d4c0 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
1d4d0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
1d4e0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e  is.** invoked on
1d4f0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
1d500 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
1d510 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
1d520 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1d530 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s made..**.** Th
1d540 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
1d550 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73  d "soft", becaus
1d560 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65  e if [sqlite3_re
1d570 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
1d580 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73  cannot.** free s
1d590 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1d5a0 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
1d5b0 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
1d5c0 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
1d5d0 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
1d5e0 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
1d5f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
1d600 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
1d610 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  .**.** A negativ
1d620 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
1d630 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
1d640 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
1d650 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
1d660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
1d670 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
1d680 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
1d690 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
1d6a0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
1d6b0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
1d6c0 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
1d6d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
1d6e0 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
1d6f0 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
1d700 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
1d710 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
1d720 2e 20 20 42 75 74 20 69 66 20 69 74 0a 2a 2a 20  .  But if it.** 
1d730 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 72 65 64  is unable to red
1d740 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  uce memory usage
1d750 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
1d760 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 69 6f 6e  limit, execution
1d770 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
1d780 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
1d790 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
1d7a0 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
1d7b0 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63  e limit is .** c
1d7c0 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
1d7d0 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
1d7e0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
1d7f0 2a 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  * The soft heap 
1d800 6c 69 6d 69 74 20 69 73 20 69 6d 70 6c 65 6d 65  limit is impleme
1d810 6e 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  nted using the [
1d820 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
1d830 6c 61 72 6d 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  larm()].** inter
1d840 66 61 63 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69  face.  Only a si
1d850 6e 67 6c 65 20 6d 65 6d 6f 72 79 20 61 6c 61 72  ngle memory alar
1d860 6d 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 69  m is available i
1d870 6e 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  n the default.**
1d880 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1d890 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
1d8a0 74 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61  t if the applica
1d8b0 74 69 6f 6e 20 61 6c 73 6f 20 75 73 65 73 20 74  tion also uses t
1d8c0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 61  he.** memory ala
1d8d0 72 6d 20 69 6e 74 65 72 66 61 63 65 20 69 74 20  rm interface it 
1d8e0 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77  will interfere w
1d8f0 69 74 68 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ith the operatio
1d900 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 73 6f 66 74  n of the.** soft
1d910 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20   heap limit and 
1d920 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1d930 6f 72 20 77 69 6c 6c 20 72 65 73 75 6c 74 2e 20  or will result. 
1d940 20 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f   .**.** Prior to
1d950 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1d960 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
1d970 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
1d980 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
1d990 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
1d9a0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
1d9b0 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
1d9c0 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
1d9d0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
1d9e0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
1d9f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1da00 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
1da10 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
1da20 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
1da30 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 76 61  threads.  The va
1da40 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f  lue specified fo
1da50 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
1da60 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 62  limit.** is an b
1da70 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61  ound on the tota
1da80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1da90 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ion for all thre
1daa0 61 64 73 2e 20 20 49 6e 0a 2a 2a 20 76 65 72 73  ads.  In.** vers
1dab0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
1dac0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
1dad0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
1dae0 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
1daf0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
1db00 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
1db10 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
1db20 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
1db30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
1db40 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
1db50 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
1db60 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
1db70 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
1db80 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
1db90 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
1dba0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
1dbb0 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
1dbc0 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
1dbd0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
1dbe0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
1dbf0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1dc00 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
1dc10 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
1dc20 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
1dc30 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1dc40 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
1dc50 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
1dc60 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
1dc70 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
1dc80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1dc90 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
1dca0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1dcb0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
1dcc0 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
1dcd0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
1dce0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
1dcf0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
1dd00 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
1dd10 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
1dd20 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
1dd30 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
1dd40 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
1dd50 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
1dd60 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
1dd70 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
1dd80 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
1dd90 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
1dda0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
1ddb0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
1ddc0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
1ddd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
1dde0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1ddf0 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
1de00 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
1de10 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
1de20 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
1de30 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
1de40 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
1de50 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
1de60 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
1de70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1de80 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
1de90 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
1dea0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
1deb0 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
1dec0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
1ded0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1dee0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
1def0 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
1df00 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
1df10 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
1df20 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
1df30 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
1df40 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
1df50 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64  tion is ommitted
1df60 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
1df70 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
1df80 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
1df90 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
1dfa0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dfb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dfc0 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
1dfd0 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
1dfe0 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
1dff0 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
1e000 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
1e010 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
1e020 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
1e030 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
1e040 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
1e050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
1e060 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
1e070 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
1e080 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
1e090 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
1e0a0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1e0b0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1e0c0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
1e0d0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
1e0e0 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
1e0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
1e100 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
1e110 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
1e120 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1e130 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
1e140 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
1e150 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
1e160 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
1e170 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
1e180 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
1e190 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
1e1a0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
1e1b0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
1e1c0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
1e1d0 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
1e1e0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
1e1f0 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
1e200 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
1e210 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
1e220 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1e230 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
1e240 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
1e250 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
1e260 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
1e270 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
1e280 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
1e290 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
1e2a0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
1e2b0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1e2c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
1e2d0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
1e2e0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1e2f0 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
1e300 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
1e310 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1e320 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
1e330 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
1e340 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
1e350 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
1e360 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
1e370 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
1e380 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
1e390 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1e3a0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
1e3b0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
1e3c0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
1e3d0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
1e3e0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
1e3f0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
1e400 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
1e410 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
1e420 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
1e430 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
1e440 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
1e450 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
1e460 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
1e470 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
1e480 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
1e490 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
1e4a0 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
1e4b0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
1e4c0 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
1e4d0 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
1e4e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
1e4f0 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
1e500 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
1e510 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
1e520 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
1e530 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
1e540 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
1e550 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1e560 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
1e570 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1e580 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
1e590 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
1e5a0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
1e5b0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
1e5c0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
1e5d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e5e0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
1e5f0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
1e600 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
1e610 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
1e620 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
1e630 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
1e640 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
1e650 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
1e660 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
1e670 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
1e680 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
1e690 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
1e6a0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
1e6b0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
1e6c0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
1e6d0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
1e6e0 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
1e6f0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
1e700 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
1e710 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
1e720 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
1e730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1e740 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
1e750 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
1e760 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
1e770 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
1e780 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
1e790 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
1e7a0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
1e7b0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
1e7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
1e7d0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
1e7e0 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 75 74 6f  f colums is auto
1e7f0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
1e800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e810 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
1e820 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70  ion.**.** Attemp
1e830 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c  t to load an SQL
1e840 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
1e850 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
1e860 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a  in the file.** z
1e870 46 69 6c 65 2e 20 20 54 68 65 20 65 6e 74 72 79  File.  The entry
1e880 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
1e890 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30    zProc may be 0
1e8a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1e8b0 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
1e8c0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65  e entry point de
1e8d0 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
1e8e0 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
1e8f0 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  t"..**.** Return
1e900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1e910 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
1e920 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
1e930 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
1e940 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ng..**.** If an 
1e950 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
1e960 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
1e970 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c 20 2a 70   0, then fill *p
1e980 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
1e990 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
1e9a0 65 78 74 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ext.  The callin
1e9b0 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
1e9c0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
1e9d0 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67  ry.** by calling
1e9e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e9f0 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69  ]..**.** Extensi
1ea00 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
1ea10 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
1ea20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1ea30 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
1ea40 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  )].** prior to c
1ea50 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20  alling this API 
1ea60 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  or an error will
1ea70 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
1ea80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
1ea90 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
1eaa0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1eab0 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
1eac0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
1ead0 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
1eae0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
1eaf0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
1eb00 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
1eb10 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
1eb20 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
1eb30 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
1eb40 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
1eb50 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
1eb60 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
1eb70 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
1eb80 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
1eb90 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
1eba0 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
1ebb0 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
1ebc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ebd0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1ebe0 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
1ebf0 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  ding.**.** So as
1ec00 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
1ec10 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
1ec20 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
1ec30 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
1ec40 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
1ec50 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
1ec60 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
1ec70 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
1ec80 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
1ec90 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
1eca0 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
1ecb0 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
1ecc0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
1ecd0 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
1ece0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
1ecf0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
1ed00 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
1ed10 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 49  n and.** off.  I
1ed20 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
1ed30 75 6c 74 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ult.  See ticket
1ed40 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61   #1863..**.** Ca
1ed50 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1ed60 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
1ed70 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
1ed80 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
1ed90 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
1eda0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
1edb0 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
1edc0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
1edd0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1ede0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
1edf0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
1ee00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ee10 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
1ee20 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
1ee30 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
1ee40 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67  ension.**.** Reg
1ee50 69 73 74 65 72 20 61 6e 20 65 78 74 65 6e 73 69  ister an extensi
1ee60 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
1ee70 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  hat is automatic
1ee80 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ally invoked.** 
1ee90 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64  whenever a new d
1eea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1eeb0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69  on is opened usi
1eec0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ng.** [sqlite3_o
1eed0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1eee0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
1eef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ef00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  )]..**.** This A
1ef10 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
1ef20 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
1ef30 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
1ef40 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
1ef50 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
1ef60 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
1ef70 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
1ef80 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
1ef90 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
1efa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
1efb0 0a 2a 2a 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65  .**.** Duplicate
1efc0 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20   extensions are 
1efd0 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c  detected so call
1efe0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1eff0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
1f000 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
1f010 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61   extension is ha
1f020 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rmless..**.** Th
1f030 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1f040 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1f050 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20  he extension in 
1f060 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74  an array.** that
1f070 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
1f080 6d 20 6d 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20  m malloc().  If 
1f090 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79  you run a memory
1f0a0 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72   leak.** checker
1f0b0 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d   on your program
1f0c0 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20   and it reports 
1f0d0 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f  a leak because o
1f0e0 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c  f this.** array,
1f0f0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71   then invoke [sq
1f100 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f  lite3_automatic_
1f110 65 78 74 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28  extension_reset(
1f120 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73  )] prior.** to s
1f130 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20  hutdown to free 
1f140 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  the memory..**.*
1f150 2a 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65  * Automatic exte
1f160 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
1f170 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
1f180 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f190 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
1f1a0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
1f1b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
1f1c0 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
1f1d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
1f1e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
1f1f0 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
1f200 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78  xtension(void *x
1f210 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f  EntryPoint);.../
1f220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f230 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
1f240 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
1f250 0a 2a 2a 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61  .**.** Disable a
1f260 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
1f270 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
1f280 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20  ic extensions.  
1f290 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  This.** routine 
1f2a0 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
1f2b0 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b  t of all prior [
1f2c0 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d 61 74 69  sqlite3_automati
1f2d0 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  c_extension()].*
1f2e0 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54  * calls..**.** T
1f2f0 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65  his call disable
1f300 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65  d automatic exte
1f310 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68  nsions in all th
1f320 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  reads..**.** Thi
1f330 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
1f340 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1f350 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
1f360 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76  ange or.** remov
1f370 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
1f380 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
1f390 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1f3a0 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
1f3b0 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f  nsion(void);.../
1f3c0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
1f3d0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
1f3e0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
1f3f0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
1f400 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
1f410 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
1f420 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
1f430 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
1f440 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
1f450 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
1f460 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
1f470 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
1f480 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
1f490 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
1f4a0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
1f4b0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
1f4c0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
1f4d0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
1f4e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
1f4f0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
1f500 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c   mechanism stabl
1f510 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
1f520 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
1f530 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
1f540 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
1f550 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
1f560 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
1f570 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
1f580 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
1f590 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
1f5a0 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
1f5b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f5c0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
1f5d0 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
1f5e0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
1f5f0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
1f600 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
1f610 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f620 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
1f630 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
1f640 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
1f650 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
1f660 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
1f670 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c  ;../*.** A modul
1f680 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20  e is a class of 
1f690 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20  virtual tables. 
1f6a0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20   Each module is 
1f6b0 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e  defined.** by an
1f6c0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
1f6d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
1f6e0 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75  ture.  This stru
1f6f0 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a  cture consists.*
1f700 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  * mostly of meth
1f710 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
1f720 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  le..*/.struct sq
1f730 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
1f740 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
1f750 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
1f760 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
1f770 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
1f780 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
1f790 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
1f7a0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
1f7b0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
1f7c0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
1f7d0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
1f7e0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
1f7f0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
1f800 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
1f810 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
1f820 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
1f830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
1f840 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
1f850 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
1f860 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
1f870 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1f880 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
1f890 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
1f8a0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
1f8b0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1f8c0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
1f8d0 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
1f8e0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
1f8f0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
1f900 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1f910 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
1f920 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
1f930 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
1f940 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
1f950 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
1f960 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
1f970 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1f980 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
1f990 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
1f9a0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
1f9b0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
1f9c0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
1f9d0 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
1f9e0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
1f9f0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
1fa00 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
1fa10 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
1fa20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
1fa30 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1fa40 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
1fa50 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
1fa60 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
1fa70 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
1fa80 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
1fa90 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
1faa0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
1fab0 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
1fac0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
1fad0 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
1fae0 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
1faf0 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
1fb00 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
1fb10 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
1fb20 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
1fb30 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
1fb40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1fb50 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
1fb60 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
1fb70 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
1fb80 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
1fb90 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
1fba0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
1fbb0 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
1fbc0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
1fbd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fbe0 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
1fbf0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1fc00 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
1fc10 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
1fc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
1fc30 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20  oid **ppArg);.. 
1fc40 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
1fc50 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
1fc60 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
1fc70 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
1fc80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
1fc90 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
1fca0 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
1fcb0 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
1fcc0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
1fcd0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
1fce0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
1fcf0 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73  ly from the xBes
1fd00 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64  tIndex.** method
1fd10 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d   of an sqlite3_m
1fd20 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c  odule.  The fiel
1fd30 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
1fd40 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
1fd50 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
1fd60 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
1fd70 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
1fd80 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
1fd90 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
1fda0 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
1fdb0 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ields..**.** The
1fdc0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
1fdd0 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
1fde0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
1fdf0 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20  aints of the.** 
1fe00 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20  form:.**.**     
1fe10 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78      column OP ex
1fe20 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f  pr.**.** Where O
1fe30 50 20 69 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e  P is =, <, <=, >
1fe40 2c 20 6f 72 20 3e 3d 2e 20 20 54 68 65 20 70 61  , or >=.  The pa
1fe50 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
1fe60 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  r is stored.** i
1fe70 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
1fe80 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f  op.  The index o
1fe90 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1fea0 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43  stored in .** aC
1feb0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
1fec0 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e  umn.  aConstrain
1fed0 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
1fee0 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
1fef0 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
1ff00 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
1ff10 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
1ff20 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
1ff30 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
1ff40 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
1ff50 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54   cannot..**.** T
1ff60 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
1ff70 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
1ff80 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
1ff90 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
1ffa0 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
1ffb0 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
1ffc0 69 63 61 74 69 6e 6f 73 20 74 6f 20 74 68 65 20  icatinos to the 
1ffd0 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
1ffe0 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
1fff0 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
20000 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
20010 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
20020 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
20030 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43  sible..** The aC
20040 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
20050 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
20060 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
20070 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74  s in the correct
20080 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65  .** form that re
20090 66 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69  fer to the parti
200a0 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
200b0 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65  ble being querie
200c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61  d..**.** Informa
200d0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
200e0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
200f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
20100 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20  erBy[]..** Each 
20110 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
20120 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
20130 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
20140 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
20150 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
20160 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
20170 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
20180 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
20190 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
201a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
201b0 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
201c0 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30    If argvIndex>0
201d0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
201e0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
201f0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
20200 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
20210 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
20220 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
20230 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
20240 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20  ry in argv.  If 
20250 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
20260 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
20270 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
20280 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
20290 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
202a0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
202b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
202c0 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
202d0 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
202e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78  e..**.** The idx
202f0 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
20300 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
20310 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
20320 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73  to xFilter..** s
20330 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
20340 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
20350 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72  xPtr if needToFr
20360 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
20370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65  ..**.** The orde
20380 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
20390 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
203a0 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  om xFilter will 
203b0 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
203c0 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
203d0 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
203e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
203f0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
20400 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
20410 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
20420 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65  .** The estimate
20430 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61  dCost value is a
20440 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68  n estimate of th
20450 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20  e cost of doing 
20460 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  the.** particula
20470 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c  r lookup.  A ful
20480 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c  l scan of a tabl
20490 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73  e with N entries
204a0 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20   should have.** 
204b0 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20  a cost of N.  A 
204c0 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66  binary search of
204d0 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e   a table of N en
204e0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
204f0 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61  e a.** cost of a
20500 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67  pproximately log
20510 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  (N)..*/.struct s
20520 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
20530 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20  o {.  /* Inputs 
20540 2a 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e  */.  const int n
20550 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
20560 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74  /* Number of ent
20570 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61  ries in aConstra
20580 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  int */.  const s
20590 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
205a0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
205b0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
205c0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
205d0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
205e0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
205f0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
20600 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
20610 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
20620 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
20630 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
20640 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
20650 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
20660 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
20670 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
20680 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
20690 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
206a0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
206b0 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
206c0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
206d0 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61   *const aConstra
206e0 69 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54 61 62  int;      /* Tab
206f0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
20700 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
20710 2f 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f  /.  const int nO
20720 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 2f  rderBy;        /
20730 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
20740 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
20750 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f  Y clause */.  co
20760 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
20770 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
20780 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
20790 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
207a0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
207b0 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
207c0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
207d0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
207e0 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
207f0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63  r ASC. */.  } *c
20800 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20  onst aOrderBy;  
20810 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
20820 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
20830 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  ..  /* Outputs *
20840 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
20850 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
20860 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
20870 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
20880 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
20890 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
208a0 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
208b0 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
208c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
208d0 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
208e0 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
208f0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
20900 6e 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  nt */.  } *const
20910 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
20920 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
20930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20940 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
20950 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
20960 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
20970 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
20980 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
20990 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
209a0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
209b0 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
209c0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
209d0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
209e0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
209f0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
20a00 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
20a10 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
20a20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
20a30 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
20a40 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
20a50 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
20a60 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
20a70 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
20a80 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
20a90 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
20aa0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
20ab0 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
20ac0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
20ad0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
20ae0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
20af0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
20b00 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
20b10 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
20b20 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
20b30 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
20b40 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
20b50 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
20b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
20b70 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
20b80 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  CH 64../*.** Thi
20b90 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  s routine is use
20ba0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
20bb0 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  new module name 
20bc0 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a  with an SQLite.*
20bd0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d  * connection.  M
20be0 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
20bf0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
20c00 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e  efore creating n
20c10 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  ew.** virtual ta
20c20 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75  bles on the modu
20c30 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73  le, or before us
20c40 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20  ing preexisting 
20c50 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
20c60 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  s of the module.
20c70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
20c80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
20c90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
20ca0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
20cb0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
20cc0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
20cd0 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
20ce0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
20cf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
20d00 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
20d10 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
20d20 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
20d30 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
20d40 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
20d50 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20  id *            
20d60 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
20d70 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
20d80 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
20d90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  );../*.** This r
20da0 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69  outine is identi
20db0 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69 74  cal to the sqlit
20dc0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
20dd0 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  () method above,
20de0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
20df0 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
20e00 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
20e10 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
20e20 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
20e30 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
20e40 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
20e50 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
20e60 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74  bles API..*/.int
20e70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
20e80 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
20e90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
20ea0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
20eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
20ec0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
20ed0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
20ee0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
20ef0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
20f00 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
20f10 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
20f20 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
20f30 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
20f40 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
20f50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
20f60 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
20f70 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
20f80 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
20f90 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
20fa0 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
20fb0 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
20fc0 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
20fd0 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  .** Every module
20fe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
20ff0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
21000 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
21010 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
21020 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
21030 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20  icular instance 
21040 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
21050 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
21060 6c 6c 0a 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65  ll.** be taylore
21070 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
21080 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
21090 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
210a0 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70  tion.   The.** p
210b0 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
210c0 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
210d0 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
210e0 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20 63  ields that are c
210f0 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20  ommon.** to all 
21100 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
21110 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69  ations..**.** Vi
21120 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
21130 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
21140 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
21150 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
21160 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
21170 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
21180 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d 73  intf() to zErrMs
21190 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
211a0 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
211b0 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
211c0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
211d0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73  d by a call to s
211e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a  qlite3_free().**
211f0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
21200 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
21210 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
21220 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
21230 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
21240 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
21250 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
21260 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
21270 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
21280 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
21290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
212a0 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
212b0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
212c0 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74  roed.  Note.** t
212d0 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  hat sqlite3_mpri
212e0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
212f0 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73 65  3_free() are use
21300 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67  d on the zErrMsg
21310 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20   field.** since 
21320 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61  virtual tables a
21330 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c  re commonly impl
21340 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61  emented in loada
21350 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77  ble extensions w
21360 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68  hich.** do not h
21370 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73 71  ave access to sq
21380 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f  lite3MPrintf() o
21390 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e  r sqlite3Free().
213a0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
213b0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
213c0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
213d0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
213e0 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
213f0 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
21400 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
21410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21420 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
21430 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
21440 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
21450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21460 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
21470 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
21480 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
21490 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
214a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
214b0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
214c0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
214d0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79   */.};../* Every
214e0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
214f0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
21500 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
21510 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
21520 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
21530 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
21540 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72  int into the vir
21550 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61  tual table and a
21560 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
21570 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
21580 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
21590 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
215a0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
215b0 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
215c0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
215d0 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
215e0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
215f0 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
21600 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
21610 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
21620 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
21630 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
21640 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
21650 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
21660 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
21670 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
21680 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
21690 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
216a0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
216b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
216c0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
216d0 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
216e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
216f0 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
21700 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
21710 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
21720 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
21730 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
21740 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
21750 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20  .** The xCreate 
21760 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
21770 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65  hods of a module
21780 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
21790 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63  ng API.** to dec
217a0 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
217b0 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
217c0 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
217d0 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
217e0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
217f0 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
21800 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21810 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
21820 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
21830 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65  ar *zCreateTable
21840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61  );../*.** Virtua
21850 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
21860 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
21870 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
21880 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
21890 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64   using the xFind
218a0 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e  Function method.
218b0 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72    But global ver
218c0 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
218d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
218e0 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
218f0 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
21900 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
21910 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
21920 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
21930 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
21940 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
21950 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
21960 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
21970 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
21980 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
21990 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
219a0 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
219b0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
219c0 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
219d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
219e0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
219f0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
21a00 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
21a10 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
21a20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
21a30 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
21a40 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
21a50 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
21a60 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
21a70 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
21a80 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  -holder function
21a90 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
21aa0 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69  rloaded.** by vi
21ab0 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
21ac0 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f  .** This API sho
21ad0 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65  uld be considere
21ae0 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69  d part of the vi
21af0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
21b00 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20  rface,.** which 
21b10 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
21b20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
21b30 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
21b40 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
21b50 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
21b60 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
21b70 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
21b80 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
21b90 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
21ba0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
21bb0 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
21bc0 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
21bd0 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
21be0 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
21bf0 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
21c00 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
21c10 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
21c20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
21c30 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
21c40 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
21c50 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
21c60 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
21c70 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
21c80 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
21c90 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
21ca0 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
21cb0 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
21cc0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
21cd0 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
21ce0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
21cf0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
21d00 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
21d10 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
21d20 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
21d30 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  nt..**.****** EX
21d40 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
21d50 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
21d60 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
21d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a  ************.*/.
21d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21d90 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
21da0 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20  Open BLOB.**.** 
21db0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
21dc0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61  he following opa
21dd0 71 75 65 20 73 74 72 75 63 74 75 72 65 20 69 73  que structure is
21de0 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70   used to .** rep
21df0 72 65 73 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68  resent an blob-h
21e00 61 6e 64 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68  andle.  A blob-h
21e10 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74 65 64  andle is created
21e20 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
21e30 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
21e40 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
21e50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
21e60 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
21e70 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
21e80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21e90 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e  blob_write()] in
21ea0 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20  terfaces.** can 
21eb0 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  be used to read 
21ec0 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73  or write small s
21ed0 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68  ubsections of th
21ee0 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b  e blob..** The [
21ef0 73 71 6c 74 69 65 33 5f 62 6c 6f 62 5f 73 69 7a  sqltie3_blob_siz
21f00 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  e()] interface r
21f10 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
21f20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69  of the.** blob i
21f30 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
21f40 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
21f50 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
21f60 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
21f70 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
21f80 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
21f90 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65  al I/O.**.** Ope
21fa0 6e 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68  n a handle to th
21fb0 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69  e blob located i
21fc0 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c  n row iRow,, col
21fd0 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a  umn zColumn, .**
21fe0 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e   table zTable in
21ff0 20 64 61 74 61 62 61 73 65 20 7a 44 62 2e 20 69   database zDb. i
22000 2e 65 2e 20 74 68 65 20 73 61 6d 65 20 62 6c 6f  .e. the same blo
22010 62 20 74 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20  b that would.** 
22020 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a  be selected by:.
22030 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
22040 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d     SELECT zColum
22050 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c  n FROM zDb.zTabl
22060 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20  e WHERE rowid = 
22070 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  iRow;.** </pre>.
22080 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61  **.** If the fla
22090 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  gs parameter is 
220a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c  non-zero, the bl
220b0 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
220c0 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72   .** read and wr
220d0 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69  ite access. If i
220e0 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62  t is zero, the b
220f0 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  lob is opened fo
22100 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73  r read .** acces
22110 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  s..**.** On succ
22120 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
22130 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
22140 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71   the new .** [sq
22150 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
22160 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  b handle] is wri
22170 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  tten to *ppBlob.
22180 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61 6e  .** Otherwise an
22190 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
221a0 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20  eturned and .** 
221b0 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65  any value writte
221c0 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f  n to *ppBlob sho
221d0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
221e0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a  by the caller..*
221f0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
22200 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73  sets the databas
22210 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63  e-handle error c
22220 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
22230 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
22240 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
22250 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
22260 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
22270 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
22280 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
22290 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
222a0 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
222b0 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
222c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
222d0 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
222e0 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
222f0 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
22300 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
22310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22320 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42  F:  Close A BLOB
22330 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c   Handle.**.** Cl
22340 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c  ose an open [sql
22350 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
22360 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74   handle]..*/.int
22370 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c   sqlite3_blob_cl
22380 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ose(sqlite3_blob
22390 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
223a0 33 52 45 46 3a 20 20 52 65 74 75 72 6e 20 54 68  3REF:  Return Th
223b0 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65  e Size Of An Ope
223c0 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74  n BLOB.**.** Ret
223d0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 69 6e 20  urn the size in 
223e0 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f  bytes of the blo
223f0 62 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  b accessible via
22400 20 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73   the open .** [s
22410 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
22420 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  ob-handle] passe
22430 64 20 61 73 20 61 6e 20 61 72 67 75 6d 65 6e 74  d as an argument
22440 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22450 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69  _blob_bytes(sqli
22460 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
22470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
22480 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
22490 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
224a0 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  ly.**.** This fu
224b0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
224c0 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
224d0 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71   an open .** [sq
224e0 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
224f0 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61  b-handle] into a
22500 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65 64   caller supplied
22510 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79   buffer..** n by
22520 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
22530 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66  copied into buff
22540 65 72 0a 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65  er.** z from the
22550 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72   open blob, star
22560 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
22570 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  Offset..**.** On
22580 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
22590 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
225a0 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
225b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
225c0 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20   | SQLite error 
225d0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
225e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
225f0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
22600 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
22610 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
22620 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
22630 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
22640 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69  oid *z, int n, i
22650 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
22660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 57  .** CAPI3REF:  W
22670 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41  rite Data Into A
22680 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
22690 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  lly.**.** This f
226a0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
226b0 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e  to write data in
226c0 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b  to an open .** [
226d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
226e0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d  lob-handle] from
226f0 20 61 20 75 73 65 72 20 73 75 70 70 6c 69 65 64   a user supplied
22700 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79   buffer..** n by
22710 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
22720 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
22730 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65  buffer.** pointe
22740 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74  d to by z into t
22750 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74  he open blob, st
22760 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
22770 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20   iOffset..**.** 
22780 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
22790 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64  blob | blob-hand
227a0 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68  le] passed as th
227b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
227c0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e  .** was not open
227d0 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20 28  ed for writing (
227e0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
227f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
22800 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a  blob_open()].***
22810 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 69 73   was zero), this
22820 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
22830 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  s [SQLITE_READON
22840 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  LY]..**.** This 
22850 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c  function may onl
22860 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e  y modify the con
22870 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c 6f  tents of the blo
22880 62 2c 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  b, it is.** not 
22890 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72  possible to incr
228a0 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ease the size of
228b0 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74 68   a blob using th
228c0 69 73 20 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66  is API. If.** of
228d0 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20  fset iOffset is 
228e0 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74 65  less than n byte
228f0 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f  s from the end o
22900 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20  f the blob, .** 
22910 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
22920 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
22930 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65  o data is writte
22940 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  n..**.** On succ
22950 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69  ess, SQLITE_OK i
22960 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
22970 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53  rwise, an .** [S
22980 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51  QLITE_ERROR | SQ
22990 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d  Lite error code]
229a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54   or an.** [SQLIT
229b0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
229c0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
229d0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
229e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
229f0 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74  blob_write(sqlit
22a00 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74  e3_blob *, const
22a10 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c   void *z, int n,
22a20 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
22a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22a40 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79   Virtual File Sy
22a50 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a  stem Objects.**.
22a60 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c  ** A virtual fil
22a70 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73  esystem (VFS) is
22a80 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
22a90 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74  ] object.** that
22aa0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20   SQLite uses to 
22ab0 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68  interact.** with
22ac0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
22ad0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
22ae0 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64 73 20 63  .  Most builds c
22af0 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69  ome with a.** si
22b00 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53  ngle default VFS
22b10 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72   that is appropr
22b20 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73  iate for the hos
22b30 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e  t computer..** N
22b40 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ew VFSes can be 
22b50 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65  registered and e
22b60 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61  xisting VFSes ca
22b70 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65  n be unregistere
22b80 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  d..** The follow
22b90 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61  ing interfaces a
22ba0 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a  re provided..**.
22bb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
22bc0 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66  fs_find() interf
22bd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
22be0 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67  inter to a VFS g
22bf0 69 76 65 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65  iven its.** name
22c00 2e 20 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73  .  Names are cas
22c10 65 20 73 65 6e 73 69 74 69 76 65 2e 20 20 49 66  e sensitive.  If
22c20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
22c30 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  ch, a NULL.** po
22c40 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
22c50 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d 65 20  d.  If zVfsName 
22c60 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
22c70 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53   default .** VFS
22c80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22c90 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72  .** New VFSes ar
22ca0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
22cb0 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  h sqlite3_vfs_re
22cc0 67 69 73 74 65 72 28 29 2e 20 20 45 61 63 68 0a  gister().  Each.
22cd0 2a 2a 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d  ** new VFS becom
22ce0 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  es the default V
22cf0 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66  FS if the makeDf
22d00 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a  lt flag is set..
22d10 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20  ** The same VFS 
22d20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
22d30 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
22d40 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e   without injury.
22d50 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65  .** To make an e
22d60 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f  xisting VFS into
22d70 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
22d80 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67  , register it ag
22d90 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ain.** with the 
22da0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65  makeDflt flag se
22db0 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65  t.  If two diffe
22dc0 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20  rent VFSes with 
22dd0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65  the.** same name
22de0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c   are registered,
22df0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
22e00 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20   undefined.  If 
22e10 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69  a.** VFS is regi
22e20 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61  stered with a na
22e30 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20  me that is NULL 
22e40 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
22e50 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ng,.** then the 
22e60 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
22e70 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e  fined..** .** Un
22e80 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
22e90 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
22ea0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
22eb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
22ec0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
22ed0 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
22ee0 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
22ef0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
22f00 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
22f10 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
22f20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
22f30 72 61 72 79 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  rary..*/.sqlite3
22f40 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
22f50 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
22f60 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
22f70 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
22f80 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
22f90 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
22fa0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
22fb0 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
22fc0 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
22fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
22fe0 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
22ff0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
23000 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
23010 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
23020 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
23030 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
23040 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
23050 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
23060 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
23070 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
23080 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
23090 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
230a0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
230b0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
230c0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
230d0 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
230e0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
230f0 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73  ions .** of thes
23100 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
23110 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
23120 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23130 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
23140 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
23150 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
23160 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
23170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23180 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
23190 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
231a0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
231b0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
231c0 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
231d0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
231e0 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
231f0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
23200 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
23210 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
23220 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
23230 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e  e SQLITE_MUTEX_N
23240 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  OOP implementati
23250 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72  on is a set of r
23260 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74  outines .** that
23270 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
23280 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
23290 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
232a0 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65   in .** a single
232b0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
232c0 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49  ation.  The SQLI
232d0 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
232e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
232f0 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
23300 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
23310 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
23320 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
23330 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20  or use on os/2, 
23340 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77  unix, and window
23350 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c  s..** .** If SQL
23360 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
23370 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
23380 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65  MUTEX_APPDEF pre
23390 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63  processor.** mac
233a0 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68  ro defined (with
233b0 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58   "-DSQLITE_MUTEX
233c0 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65  _APPDEF=1"), the
233d0 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  n no mutex.** im
233e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
233f0 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68  included with th
23400 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a  e library.  The.
23410 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61  ** mutex interfa
23420 63 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  ce routines defi
23430 6e 65 64 20 68 65 72 65 20 62 65 63 6f 6d 65 20  ned here become 
23440 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65  external.** refe
23450 72 65 6e 63 65 73 20 69 6e 20 74 68 65 20 53 51  rences in the SQ
23460 4c 69 74 65 20 6c 69 62 72 61 72 79 20 66 6f 72  Lite library for
23470 20 77 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74   which implement
23480 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62  ations.** must b
23490 65 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  e provided by th
234a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
234b0 54 68 69 73 20 66 61 63 69 6c 69 74 79 20 61 6c  This facility al
234c0 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  lows an.** appli
234d0 63 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b  cation that link
234e0 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
234f0 20 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73 20   to provide its 
23500 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  own mutex.** imp
23510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
23520 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f  out having to mo
23530 64 69 66 79 20 74 68 65 20 53 51 4c 69 74 65 20  dify the SQLite 
23540 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  core..**.** The 
23550 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
23560 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c  loc() routine al
23570 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a  locates a new.**
23580 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72   mutex and retur
23590 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
235a0 69 74 2e 20 20 49 66 20 69 74 20 72 65 74 75 72  it.  If it retur
235b0 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
235c0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
235d0 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
235e0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69  allocated.  SQLi
235f0 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
23600 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
23610 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
23620 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a    The argument.*
23630 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
23640 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
23650 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
23660 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
23670 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
23680 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
23690 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
236a0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
236b0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
236c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
236d0 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
236e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
236f0 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
23700 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
23710 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
23720 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
23730 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
23740 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
23750 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
23760 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
23770 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74   first two const
23780 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74  ants cause sqlit
23790 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
237a0 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20   to create.** a 
237b0 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20  new mutex.  The 
237c0 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63  new mutex is rec
237d0 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49  ursive when SQLI
237e0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
237f0 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75  VE.** is used bu
23800 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c  t not necessaril
23810 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45  y so when SQLITE
23820 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75  _MUTEX_FAST is u
23830 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65  sed..** The mute
23840 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
23850 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
23860 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
23870 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
23880 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23890 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
238a0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
238b0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
238c0 61 6e 74 20 74 6f 2e 20 20 42 75 74 20 53 51 4c  ant to.  But SQL
238d0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65  ite will only re
238e0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76  quest a recursiv
238f0 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61  e mutex in.** ca
23900 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61  ses where it rea
23910 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20  lly needs one.  
23920 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d  If a faster non-
23930 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a  recursive mutex.
23940 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23950 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  n is available o
23960 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66  n the host platf
23970 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73  orm, the mutex s
23980 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68  ubsystem.** migh
23990 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20  t return such a 
239a0 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73  mutex in respons
239b0 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  e to SQLITE_MUTE
239c0 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68  X_FAST..**.** Th
239d0 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20  e other allowed 
239e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71  parameters to sq
239f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
23a00 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a  c() each return.
23a10 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
23a20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73  a static preexis
23a30 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 46 6f 75  ting mutex.  Fou
23a40 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  r static mutexes
23a50 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20   are.** used by 
23a60 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73  the current vers
23a70 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ion of SQLite.  
23a80 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
23a90 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79  of SQLite.** may
23aa0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
23ab0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20  static mutexes. 
23ac0 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   Static mutexes 
23ad0 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  are for internal
23ae0 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
23af0 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  e only.  Applica
23b00 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53  tions that use S
23b10 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68  QLite mutexes sh
23b20 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79  ould.** use only
23b30 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
23b40 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  exes returned by
23b50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
23b60 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f  ST or.** SQLITE_
23b70 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e  MUTEX_RECURSIVE.
23b80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
23b90 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
23ba0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
23bb0 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
23bc0 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
23bd0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
23be0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
23bf0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
23c00 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
23c10 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
23c20 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
23c30 79 20 63 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72  y call.  But for
23c40 20 74 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20   the static .** 
23c50 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
23c60 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
23c70 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
23c80 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
23c90 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
23ca0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
23cb0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
23cc0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64  free() routine d
23cd0 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65  eallocates a pre
23ce0 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63  viously.** alloc
23cf0 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74  ated dynamic mut
23d00 65 78 2e 20 20 53 51 4c 69 74 65 20 69 73 20 63  ex.  SQLite is c
23d10 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
23d20 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
23d30 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
23d40 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20   it allocates.  
23d50 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  The dynamic mute
23d60 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  xes must not be 
23d70 69 6e 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20  in .** use when 
23d80 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63  they are dealloc
23d90 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e  ated.  Attemptin
23da0 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  g to deallocate 
23db0 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65  a static.** mute
23dc0 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  x results in und
23dd0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
23de0 20 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64    SQLite never d
23df0 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
23e00 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
23e10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23e20 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
23e30 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
23e40 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
23e50 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
23e60 65 72 20 61 20 6d 75 74 65 78 2e 20 20 49 66 20  er a mutex.  If 
23e70 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69  another thread i
23e80 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e  s already within
23e90 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73   the mutex,.** s
23ea0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
23eb0 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20  er() will block 
23ec0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
23ed0 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74  x_try() will ret
23ee0 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  urn.** SQLITE_BU
23ef0 53 59 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  SY.  The sqlite3
23f00 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74  _mutex_try() int
23f10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 53  erface returns S
23f20 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e  QLITE_OK.** upon
23f30 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
23f40 79 2e 20 20 4d 75 74 65 78 65 73 20 63 72 65 61  y.  Mutexes crea
23f50 74 65 64 20 75 73 69 6e 67 20 53 51 4c 49 54 45  ted using SQLITE
23f60 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
23f70 20 63 61 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72   can.** be enter
23f80 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
23f90 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  s by the same th
23fa0 72 65 61 64 2e 20 20 49 6e 20 73 75 63 68 20 63  read.  In such c
23fb0 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74  ases the,.** mut
23fc0 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65  ex must be exite
23fd0 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65  d an equal numbe
23fe0 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72  r of times befor
23ff0 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  e another thread
24000 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20  .** can enter.  
24010 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  If the same thre
24020 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65  ad tries to ente
24030 72 20 61 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64  r any other kind
24040 20 6f 66 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72   of mutex.** mor
24050 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65  e than once, the
24060 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
24070 65 66 69 6e 65 64 2e 20 20 20 53 51 4c 69 74 65  efined.   SQLite
24080 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
24090 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
240a0 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
240b0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a  use of mutexes..
240c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
240d0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
240e0 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
240f0 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
24100 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
24110 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
24120 20 74 68 72 65 61 64 2e 20 20 54 68 65 20 62 65   thread.  The be
24130 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
24140 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
24150 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
24160 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
24170 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
24180 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
24190 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
241a0 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ted.  SQLite wil
241b0 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
241c0 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ther..**.** See 
241d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
241e0 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
241f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
24200 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
24210 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
24220 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
24230 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
24240 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
24250 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
24260 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
24270 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
24280 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
24290 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
242a0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
242b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
242c0 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
242d0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
242e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
242f0 65 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52  ex Verifcation R
24300 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68  outines.**.** Th
24310 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
24320 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74  held() and sqlit
24330 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
24340 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  () routines.** a
24350 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
24360 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72  use inside asser
24370 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  t() statements. 
24380 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
24390 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74  .** never uses t
243a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78  hese routines ex
243b0 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61  cept inside an a
243c0 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c  ssert() and appl
243d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ications.** are 
243e0 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f  advised to follo
243f0 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68  w the lead of th
24400 65 20 63 6f 72 65 2e 20 20 54 68 65 20 63 6f 72  e core.  The cor
24410 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
24420 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
24430 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
24440 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
24450 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
24460 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
24470 55 47 20 66 6c 61 67 2e 20 20 45 78 74 65 72 6e  UG flag.  Extern
24480 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  al mutex impleme
24490 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
244a0 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f  only required to
244b0 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72   provide these r
244c0 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54  outines if SQLIT
244d0 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65  E_DEBUG is.** de
244e0 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45  fined and if NDE
244f0 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e  BUG is not defin
24500 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
24510 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
24520 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
24530 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
24540 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
24550 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
24560 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
24570 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
24580 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  thread..**.** Th
24590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
245a0 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
245b0 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72   to provided ver
245c0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a  sions of these.*
245d0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
245e0 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a  actually work..*
245f0 2a 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  * If the impleme
24600 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
24610 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
24620 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
24630 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
24640 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
24650 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
24660 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 79 73 20  .** that always 
24670 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
24680 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
24690 20 67 65 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a   get spurious.**
246a0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75   assertion failu
246b0 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  res..**.** If th
246c0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
246d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
246e0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
246f0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
24700 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
24710 72 65 74 75 72 6e 20 31 2e 20 20 54 68 69 73 20  return 1.  This 
24720 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
24730 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
24740 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
24750 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
24760 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
24770 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
24780 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
24790 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
247a0 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
247b0 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
247c0 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
247d0 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
247e0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
247f0 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
24800 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f  g the.** call to
24810 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
24820 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73  eld() to fail, s
24830 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  o a non-zero ret
24840 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70  urn is.** the ap
24850 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20  propriate thing 
24860 74 6f 20 64 6f 2e 20 20 54 68 65 20 73 71 6c 69  to do.  The sqli
24870 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
24880 64 28 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63  d() .** interfac
24890 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65  e should also re
248a0 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65  turn 1 when give
248b0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
248c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
248d0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69  _mutex_held(sqli
248e0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
248f0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
24900 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  otheld(sqlite3_m
24910 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
24920 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54  API3REF: Mutex T
24930 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ypes.**.** The [
24940 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
24950 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
24960 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
24970 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
24980 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
24990 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
249a0 6e 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  nts..*/.#define 
249b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
249c0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a  T             0.
249d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
249e0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20  UTEX_RECURSIVE  
249f0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
24a00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24a10 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a  TIC_MASTER    2.
24a20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
24a30 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20  UTEX_STATIC_MEM 
24a40 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69        3  /* sqli
24a50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a  te3_malloc() */.
24a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
24a70 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
24a80 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
24a90 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
24aa0 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ry() */.#define 
24ab0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24ac0 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20  TIC_PRNG      5 
24ad0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64   /* sqlite3_rand
24ae0 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  om() */.#define 
24af0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
24b00 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20  TIC_LRU       6 
24b10 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73   /* lru page lis
24b20 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64  t */.../*.** Und
24b30 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20  o the hack that 
24b40 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e  converts floatin
24b50 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f  g point types to
24b60 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20   integer for.** 
24b70 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73  builds on proces
24b80 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f  sors without flo
24b90 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
24ba0 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ort..*/.#ifdef S
24bb0 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
24bc0 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65  ING_POINT.# unde
24bd0 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a  f double.#endif.
24be0 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70  .#ifdef __cplusp
24bf0 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66  lus.}  /* End of
24c00 20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22   the 'extern "C"
24c10 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69  ' block */.#endi
24c20 66 0a 23 65 6e 64 69 66 0a                       f.#endif.