/ Hex Artifact Content
Login

Artifact 1fb6748ebd4c36b8476c03791009585fd5cfcf3b:


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 32 35 20 32 30 30 37 2f  in,v 1.225 2007/
05f0: 30 38 2f 31 36 20 31 33 3a 30 31 3a 34 35 20 64  08/16 13:01:45 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 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  open], [sqlite3_
1180: 6f 70 65 6e 31 36 5d 2c 20 61 6e 64 0a 2a 2a 20  open16], and.** 
1190: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
11a0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
11b0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
11c0: 73 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  s.** and [sqlite
11d0: 33 5f 63 6c 6f 73 65 5d 20 69 73 20 69 74 73 20  3_close] is its 
11e0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
11f0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1200: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1210: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1220: 33 5f 70 72 65 70 61 72 65 5f 76 32 5d 2c 20 5b  3_prepare_v2], [
1230: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1240: 75 6e 63 74 69 6f 6e 5d 2c 20 61 6e 64 0a 2a 2a  unction], and.**
1250: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1260: 69 6d 65 6f 75 74 5d 20 74 6f 20 6e 61 6d 65 20  imeout] to name 
1270: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1280: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74  are methods on t
1290: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a  his.** object..*
12a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
12b0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
12c0: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
12d0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
12e0: 65 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53  er Types.**.** S
12f0: 6f 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f  ome compilers do
1300: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
1310: 20 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74   "long long" dat
1320: 61 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61  atype.  So we ha
1330: 76 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70  ve.** to do comp
1340: 69 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79  iler-specific ty
1350: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
1360: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
1370: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
1380: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
1390: 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
13a0: 74 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20  tions require a 
13b0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61  64-bit integer a
13c0: 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f  rguments..** Tho
13d0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  se interfaces ar
13e0: 65 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67  e declared using
13f0: 20 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a   this typedef..*
1400: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1410: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1420: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1430: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1440: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1450: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
1460: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1470: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
1480: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
1490: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
14a0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
14b0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
14c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
14d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
14e0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
14f0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
1500: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
1510: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
1520: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1530: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
1540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1550: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
1560: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
1570: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
1580: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
1590: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
15a0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
15b0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
15c0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
15d0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
15e0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
15f0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
1600: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
1610: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1620: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
1630: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
1640: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
1650: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
1660: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
1670: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
1680: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1690: 43 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69  Call this functi
16a0: 6f 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  on with a pointe
16b0: 72 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  r to a structure
16c0: 20 74 68 61 74 20 77 61 73 20 70 72 65 76 69 6f   that was previo
16d0: 75 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  usly.** returned
16e0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
16f0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1700: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
1710: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1720: 76 32 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f  v2()] and the co
1730: 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61  rresponding data
1740: 62 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20  base will by.** 
1750: 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c  closed..**.** Al
1760: 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  l SQL statements
1770: 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1780: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1790: 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
17a0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
17b0: 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65  v2()] must be de
17c0: 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73  stroyed using [s
17d0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17e0: 29 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  )].** before thi
17f0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
1800: 6c 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  led. Otherwise, 
1810: 53 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72  SQLITE_BUSY is r
1820: 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a  eturned and the.
1830: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1840: 65 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f  ection remains o
1850: 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
1860: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
1870: 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  3 *);../*.** The
1880: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
1890: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
18a0: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
18b0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
18c0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
18d0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
18e0: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
18f0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
1900: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
1910: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
1920: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
1930: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
1940: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
1950: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
1960: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
1970: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20  Interface.**.** 
1980: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
1990: 73 20 75 73 65 64 20 74 6f 20 64 6f 20 61 20 6f  s used to do a o
19a0: 6e 65 2d 74 69 6d 65 20 65 76 61 6c 75 61 74 61  ne-time evaluata
19b0: 74 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a 20  tion of zero.** 
19c0: 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 74  or more SQL stat
19d0: 65 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38 20 74  ements.  UTF-8 t
19e0: 65 78 74 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ext of the SQL s
19f0: 74 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a 20  tatements to.** 
1a00: 62 65 20 65 76 61 6c 75 74 65 64 20 69 73 20 70  be evaluted is p
1a10: 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 20  assed in as the 
1a20: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a30: 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74  .  The statement
1a40: 73 0a 2a 2a 20 61 72 65 20 70 72 65 70 61 72 65  s.** are prepare
1a50: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 73 69  d one by one usi
1a60: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1a70: 61 72 65 28 29 5d 2c 20 65 76 61 6c 75 61 74 65  are()], evaluate
1a80: 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
1a90: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 74 68 65  te3_step()], the
1aa0: 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e  n destroyed usin
1ab0: 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1ac0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ize()]..**.** If
1ad0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
1ae0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1af0: 74 73 20 61 72 65 20 71 75 65 72 69 65 73 2c 20  ts are queries, 
1b00: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  then.** the call
1b10: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70  back function sp
1b20: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33  ecified by the 3
1b30: 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  rd parameter is.
1b40: 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  ** invoked once 
1b50: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
1b60: 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  the query result
1b70: 2e 20 20 54 68 69 73 20 63 61 6c 6c 62 61 63 6b  .  This callback
1b80: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72 6d 61  .** should norma
1b90: 6c 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20 49  lly return 0.  I
1ba0: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bb0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
1bc0: 6f 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65 6e 20  o.** value then 
1bd0: 74 68 65 20 71 75 65 72 79 20 69 73 20 61 62 6f  the query is abo
1be0: 72 74 65 64 2c 20 61 6c 6c 20 73 75 62 73 65 71  rted, all subseq
1bf0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
1c00: 6e 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69 70 70  nts.** are skipp
1c10: 65 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69 74  ed and the sqlit
1c20: 65 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74 69  e3_exec() functi
1c30: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 53  on returns the S
1c40: 51 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a 0a  QLITE_ABORT..**.
1c50: 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
1c60: 65 74 65 72 20 74 6f 20 74 68 69 73 20 69 6e 74  eter to this int
1c70: 65 72 66 61 63 65 20 69 73 20 61 6e 20 61 72 62  erface is an arb
1c80: 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 20 74  itrary pointer t
1c90: 68 61 74 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  hat is.** passed
1ca0: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
1cb0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1cc0: 6e 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  n as its first p
1cd0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1ce0: 54 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  The 2nd paramete
1cf0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1d00: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
1d10: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1d20: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 71 75  olumns in the qu
1d30: 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 65  ery result.  The
1d40: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1d50: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  o the callback.*
1d60: 2a 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  * is an array of
1d70: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
1d80: 20 74 68 65 20 76 61 6c 75 65 73 20 66 6f 72 20   the values for 
1d90: 65 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  each column.** a
1da0: 73 20 65 78 74 72 61 63 74 65 64 20 75 73 69 6e  s extracted usin
1db0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  g [sqlite3_colum
1dc0: 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20 54 68  n_text()]..** Th
1dd0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
1de0: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1df0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73  is an array of s
1e00: 74 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e  trings.** obtain
1e10: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1e20: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
1e30: 20 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20   and holding.** 
1e40: 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63  the names of eac
1e50: 68 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  h column..**.** 
1e60: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1e70: 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55 4c  ction may be NUL
1e80: 4c 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65 72  L, even for quer
1e90: 69 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20  ies.  A NULL.** 
1ea0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
1eb0: 61 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a 75  an error.  It ju
1ec0: 73 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f  st means that no
1ed0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c   callback.** wil
1ee0: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  l be invoked..**
1ef0: 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20  .** If an error 
1f00: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72  occurs while par
1f10: 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69  sing or evaluati
1f20: 6e 67 20 74 68 65 20 53 51 4c 20 28 62 75 74 0a  ng the SQL (but.
1f30: 2a 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78 65  ** not while exe
1f40: 63 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  cuting the callb
1f50: 61 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70 70  ack) then an app
1f60: 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a 2a  ropriate error.*
1f70: 2a 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  * message is wri
1f80: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
1f90: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1fa0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fb0: 5d 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73 67  ] and.** *errmsg
1fc0: 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1fd0: 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61 67  t to that messag
1fe0: 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  e.  The calling 
1ff0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 72  function.** is r
2000: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
2010: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
2020: 79 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  y that holds the
2030: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2040: 65 2e 20 20 20 55 73 65 20 5b 73 71 6c 69 74 65  e.   Use [sqlite
2050: 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 74 68  3_free()] for th
2060: 69 73 2e 20 20 49 66 20 65 72 72 6d 73 67 3d 3d  is.  If errmsg==
2070: 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 6e 6f  NULL,.** then no
2080: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
2090: 73 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e 0a  s ever written..
20a0: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
20b0: 20 76 61 6c 75 65 20 69 73 20 69 73 20 53 51 4c   value is is SQL
20c0: 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65 20  ITE_OK if there 
20d0: 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61 6e  are no errors an
20e0: 64 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72 20  d.** some other 
20f0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 74  [SQLITE_OK | ret
2100: 75 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68 65  urn code] if the
2110: 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  re is an error. 
2120: 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
2130: 6c 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  lar return value
2140: 20 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20   depends on the 
2150: 74 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a  type of error. .
2160: 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  **.*/.int sqlite
2170: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
2180: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
2190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21a0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
21b0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
21c0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
21d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
21f0: 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a  to be evaluted *
2200: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
2210: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
2220: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
2230: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
2240: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
2250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2270: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
2280: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
2290: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
22a0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
22b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22c0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
22d0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
22e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22f0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
2300: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2310: 45 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  E_OK.**.** Many 
2320: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
2330: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
2340: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
2350: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
2360: 6e 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72  n.** above in or
2370: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
2380: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
2390: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ure..**.** The r
23a0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f 76  esult codes abov
23b0: 65 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6f  e are the only o
23c0: 6e 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  nes returned by 
23d0: 53 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a 2a  SQLite in its.**
23e0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
23f0: 72 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72  ration.  However
2400: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  , the [sqlite3_e
2410: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
2420: 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20 63  odes()].** API c
2430: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65  an be used to se
2440: 74 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  t a database con
2450: 6e 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75 72  nectoin to retur
2460: 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 0a  n more detailed.
2470: 2a 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 2e  ** result codes.
2480: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2490: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
24a0: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
24b0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a 0a  esult codes].**.
24c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24d0: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
24e0: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
24f0: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
2500: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
2510: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
2520: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
2530: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
2540: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
2550: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
2560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2570: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
2580: 20 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 72   NOT USED. Inter
2590: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
25a0: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
25b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
25c0: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
25d0: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
25e0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
25f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
2600: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
2610: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2620: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
2630: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
2640: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
2650: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
2660: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
2670: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
2680: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
2690: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
26a0: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
26b0: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
26c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
26d0: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
26e0: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
26f0: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
2700: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
2710: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
2720: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
2730: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
2740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2750: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
2760: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
2770: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
2780: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
2790: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
27a0: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
27b0: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
27c0: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
27d0: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
27e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
27f0: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
2800: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
2810: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
2820: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
2830: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
2840: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54  D    12   /* NOT
2850: 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20   USED. Table or 
2860: 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64  record not found
2870: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2880: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
2890: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
28a0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
28b0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
28c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
28d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
28e0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
28f0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
2900: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
2910: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
2920: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f  OL    15   /* NO
2930: 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65  T USED. Database
2940: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
2950: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
2960: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
2970: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
2980: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
2990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
29a0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
29b0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
29c0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
29d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
29e0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
29f0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
2a00: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
2a10: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
2a20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
2a30: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
2a40: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72 61  rt due to contra
2a50: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
2a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a70: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
2a80: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
2a90: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
2aa0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
2ab0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
2ac0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
2ad0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
2ae0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
2af0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
2b00: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
2b10: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
2b20: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
2b30: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
2b40: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
2b50: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
2b60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b70: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
2b80: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
2b90: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
2ba0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
2bb0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
2bc0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
2bd0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2be0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
2bf0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
2c00: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
2c10: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
2c20: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
2c30: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
2c40: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
2c50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
2c60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
2c70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
2c80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
2c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ca0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
2cb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
2cc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
2cd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
2ce0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
2cf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
2d00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
2d10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
2d20: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
2d30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
2d40: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
2d50: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
2d60: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
2d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64 65   result codes de
2d80: 73 63 72 69 62 65 64 20 61 74 20 72 65 73 75 6c  scribed at resul
2d90: 74 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76 65  t-codes.  Howeve
2da0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
2db0: 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20  s shown that.** 
2dc0: 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 65  many of these re
2dd0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
2de0: 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e 65  oo course-graine
2df0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
2e00: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
2e10: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
2e20: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
2e30: 20 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69 6b   users might lik
2e40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
2e50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
2e60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
2e70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
2e80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
2e90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
2ea0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
2eb0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
2ec0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
2ed0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
2ee0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
2ef0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 20   about errors.  
2f00: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
2f10: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
2f20: 61 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62 6c  abled (or disabl
2f30: 65 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63 68  ed) for .** each
2f40: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2f50: 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  nection using th
2f60: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
2f70: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
2f80: 28 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20  ()] API..** .** 
2f90: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
2fa0: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
2fb0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
2fc0: 6c 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a 2a  listed above..**
2fd0: 20 57 65 20 65 78 70 65 63 74 20 74 68 65 20 6e   We expect the n
2fe0: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
2ff0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
3000: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a  ill be expand.**
3010: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66   over time.  Sof
3020: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20  tware that uses 
3030: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3040: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70  codes should exp
3050: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65  ect.** to see ne
3060: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69  w result codes i
3070: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
3080: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
3090: 0a 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69 63  .** The symbolic
30a0: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74   name for an ext
30b0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
30c0: 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e  e always contain
30d0: 73 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 70  s a related.** p
30e0: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f  rimary result co
30f0: 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 20  de as a prefix. 
3100: 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   Primary result 
3110: 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61 20  codes contain a 
3120: 73 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 68  single.** "_" ch
3130: 61 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e 64  aracter.  Extend
3140: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3150: 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d  contain two or m
3160: 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  ore "_" characte
3170: 72 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 72  rs..** The numer
3180: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
3190: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
31a0: 6f 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 65  ode can be conve
31b0: 72 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63  rted to its.** c
31c0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69  orresponding pri
31d0: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
31e0: 20 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20   by masking off 
31f0: 74 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 65  the lower 8 byte
3200: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
3210: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
3220: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
3230: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
3240: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
3250: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
3260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3270: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
3280: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3290: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
32a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
32b0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
32c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
32d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
32e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
32f0: 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  TE         (SQLI
3300: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
3310: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3320: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
3330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3340: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
3350: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3360: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
3370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3380: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
3390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
33a0: 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c  UNCATE      (SQL
33b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
33c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
33d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
33e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
33f0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
3400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3410: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
3420: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3430: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
3440: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
3450: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  DLOCK        (SQ
3460: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
3470: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
3480: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
3490: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
34a0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
34b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34c0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
34d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
34e0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f 2a  R | (11<<8))../*
34f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
3500: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
3510: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
3520: 2a 2a 20 43 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ** Combination o
3530: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3540: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 75  bit values are u
3550: 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 74 68  sed as the.** th
3560: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
3570: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
3580: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
3590: 65 20 61 6e 64 0a 2a 2a 20 61 73 20 66 6f 75 72  e and.** as four
35a0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
35b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
35c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
35d0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
35e0: 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  **.*/.#define SQ
35f0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
3600: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
3610: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
3620: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
3630: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
3640: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
3650: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
3660: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
3670: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
3680: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
3690: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
36a0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
36b0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
36c0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
36d0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
36e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
36f0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
3700: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
3710: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
3720: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
3730: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
3740: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
3750: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
3760: 30 30 33 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00300.#define SQ
3770: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
3780: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
3790: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
37a0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
37b0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
37c0: 30 30 35 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00500.#define SQ
37d0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
37e0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
37f0: 30 30 36 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00600../*.** CAP
3800: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
3810: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
3820: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
3830: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
3840: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
3850: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
3860: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
3870: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
3880: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
3890: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   the following.*
38a0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
38b0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
38c0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
38d0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
38e0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
38f0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
3900: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
3910: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
3920: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
3930: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
3940: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
3950: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
3960: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
3970: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
3980: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
3990: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
39a0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
39b0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
39c0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
39d0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
39e0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
39f0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
3a00: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
3a10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
3a20: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
3a30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
3a40: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
3a50: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
3a60: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
3a70: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
3a80: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
3a90: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
3aa0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
3ab0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
3ac0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
3ad0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
3ae0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
3af0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
3b00: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
3b10: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
3b20: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
3b30: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
3b40: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
3b50: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
3b60: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ite()..*/.#defin
3b70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3b80: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30  TOMIC          0
3b90: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
3ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3bb0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30  TOMIC512       0
3bc0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
3bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3be0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30  TOMIC1K        0
3bf0: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
3c00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3c10: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30  TOMIC2K        0
3c20: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
3c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3c40: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30  TOMIC4K        0
3c50: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
3c60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3c70: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30  TOMIC8K        0
3c80: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
3c90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3ca0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30  TOMIC16K       0
3cb0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3cd0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30  TOMIC32K       0
3ce0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
3cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3d00: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30  TOMIC64K       0
3d10: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
3d20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
3d30: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30  AFE_APPEND     0
3d40: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
3d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
3d60: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30  EQUENTIAL      0
3d70: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a  x00000400../*.**
3d80: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
3d90: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
3da0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
3db0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
3dc0: 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 76 61  owing integer va
3dd0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
3de0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
3df0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
3e00: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
3e10: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
3e20: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
3e30: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
3e40: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
3e50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
3e60: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
3e70: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
3e80: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
3e90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
3ea0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
3eb0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
3ec0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
3ed0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
3ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
3ef0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
3f00: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
3f10: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
3f20: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
3f30: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
3f40: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
3f50: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
3f60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
3f70: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
3f80: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
3f90: 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 6f  nation of the fo
3fa0: 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
3fb0: 76 61 6c 75 65 73 20 61 73 0a 2a 2a 20 74 68 65  values as.** the
3fc0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
3fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
3ff0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
4000: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
4010: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
4020: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
4030: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
4040: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
4050: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
4060: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
4070: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 20 54 68   be flushed.  Th
4080: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42 41  e SQLITE_SYNC_BA
4090: 52 52 49 45 52 20 66 6c 61 67 0a 2a 2a 20 6d 65  RRIER flag.** me
40a0: 61 6e 73 20 74 68 61 74 20 74 68 65 20 6e 6f 74  ans that the not
40b0: 68 69 6e 67 20 61 63 74 75 61 6c 6c 79 20 6e 65  hing actually ne
40c0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 68 65  eds to be synche
40d0: 64 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  d to mass storag
40e0: 65 2c 0a 2a 2a 20 62 75 74 20 61 6c 6c 20 77 72  e,.** but all wr
40f0: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 74  ite operations t
4100: 68 61 74 20 6f 63 63 75 72 20 62 65 66 6f 72 65  hat occur before
4110: 20 74 68 65 20 62 61 72 72 69 65 72 20 6d 75 73   the barrier mus
4120: 74 20 63 6f 6d 70 6c 65 74 65 0a 2a 2a 20 62 65  t complete.** be
4130: 66 6f 72 65 20 61 6e 79 20 77 72 69 74 65 20 6f  fore any write o
4140: 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  perations that o
4150: 63 63 75 72 20 61 66 74 65 72 20 74 68 65 20 62  ccur after the b
4160: 61 72 72 69 65 72 20 62 65 67 69 6e 2e 0a 2a 2a  arrier begin..**
4170: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
4180: 5f 4e 4f 52 4d 41 4c 20 6d 65 61 6e 73 20 74 6f  _NORMAL means to
4190: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
41a0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
41b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
41c0: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
41d0: 73 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d  s to use Mac OS-
41e0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
41f0: 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 66  .** instead of f
4200: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  sync()..*/.#defi
4210: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42  ne SQLITE_SYNC_B
4220: 41 52 52 49 45 52 20 20 20 20 20 20 20 30 78 30  ARRIER       0x0
4230: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4240: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
4250: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
4270: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
4280: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
4290: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
42a0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
42b0: 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  10.../*.** CAPI3
42c0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
42d0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
42e0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
42f0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
4300: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
4310: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
4320: 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   OS.** interface
4330: 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64   layer.  Individ
4340: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
4350: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
4360: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
4370: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
4380: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
4390: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
43a0: 65 6c 64 73 0a 2a 2a 20 6f 66 20 74 68 65 69 72  elds.** of their
43b0: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
43c0: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
43d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
43e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
43f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
4400: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
4410: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
4420: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
4430: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
4440: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
4450: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4460: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
4470: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
4480: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 73 74 72  te3_file {.  str
4490: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
44a0: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
44b0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 67  ;  /* Methods ag
44c0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
44d0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
44e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
44f0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
4500: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
4510: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
4520: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
4530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
4540: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
4550: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
4560: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
4570: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
4580: 67 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  g object.  This 
4590: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
45a0: 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73  he.** methods us
45b0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
45c0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
45d0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
45e0: 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n file..**.** Th
45f0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
4600: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
4610: 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f 53   one of SQLITE_S
4620: 59 4e 43 5f 42 41 52 52 49 45 52 2c 0a 2a 2a 20  YNC_BARRIER,.** 
4630: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
4640: 41 4c 2c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  AL, SQLITE_SYNC_
4650: 46 55 4c 4c 2e 20 20 54 68 65 20 66 69 72 73 74  FULL.  The first
4660: 20 63 68 6f 69 63 65 20 6d 65 61 6e 73 20 74 68   choice means th
4670: 61 74 0a 2a 2a 20 64 61 74 61 20 69 73 20 6e 6f  at.** data is no
4680: 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 79  t necessarily sy
4690: 6e 63 65 64 20 74 6f 20 64 69 73 6b 20 63 6f 6d  nced to disk com
46a0: 70 6c 65 74 65 6c 79 2c 20 6f 6e 6c 79 20 74 68  pletely, only th
46b0: 61 74 0a 2a 2a 20 61 6c 6c 20 77 72 69 74 65 73  at.** all writes
46c0: 20 74 68 61 74 20 6f 63 63 75 72 20 62 65 66 6f   that occur befo
46d0: 72 65 20 74 68 65 20 73 79 6e 63 20 63 6f 6d 70  re the sync comp
46e0: 6c 65 74 65 20 62 65 66 6f 72 65 20 61 6e 79 0a  lete before any.
46f0: 2a 2a 20 77 72 69 74 65 73 20 74 68 61 74 20 6f  ** writes that o
4700: 63 63 75 72 20 61 66 74 65 72 20 74 68 65 20 73  ccur after the s
4710: 79 6e 63 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ync.  The second
4720: 20 66 6c 61 67 20 69 73 20 74 68 65 0a 2a 2a 20   flag is the.** 
4730: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 20  normal fsync(). 
4740: 20 54 68 65 20 74 68 69 72 64 20 66 6c 61 67 20   The third flag 
4750: 69 73 20 61 20 4f 53 2d 58 20 73 74 79 6c 65 20  is a OS-X style 
4760: 66 75 6c 6c 73 79 6e 63 2e 0a 2a 2a 20 54 68 65  fullsync..** The
4770: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
4780: 41 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  A flag may be OR
4790: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
47a0: 65 20 74 68 61 74 20 6f 6e 6c 79 0a 2a 2a 20 74  e that only.** t
47b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
47c0: 69 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  ile and not its 
47d0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
47e0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a  e synced..** .**
47f0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
4800: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
4810: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
4820: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 53 51 4c 49 54   one of.** SQLIT
4830: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 2c 20 53 51 4c  E_LOCK_NONE, SQL
4840: 49 54 45 5f 4c 4f 43 4b 5f 52 45 41 44 2c 20 53  ITE_LOCK_READ, S
4850: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4860: 56 45 44 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c  VED,.** SQLITE_L
4870: 4f 43 4b 5f 50 45 4e 44 49 4e 47 2c 20 6f 72 20  OCK_PENDING, or 
4880: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
4890: 55 53 49 56 45 2e 20 20 78 4c 6f 63 6b 28 29 0a  USIVE.  xLock().
48a0: 2a 2a 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  ** increases the
48b0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
48c0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
48d0: 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43  ock.  .** The xC
48e0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
48f0: 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a  () method looks.
4900: 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79  ** to see if any
4910: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4920: 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20  tion, either in 
4930: 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20  this.** process 
4940: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
4950: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
4960: 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44  ding an RESERVED
4970: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
4980: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
4990: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
49a0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
49b0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
49c0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
49d0: 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20   if not..** .** 
49e0: 78 42 72 65 61 6b 4c 6f 63 6b 28 29 20 61 74 74  xBreakLock() att
49f0: 65 6d 70 74 73 20 74 6f 20 62 72 65 61 6b 20 61  empts to break a
4a00: 20 6c 6f 63 6b 20 68 65 6c 64 20 62 79 20 61 6e   lock held by an
4a10: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2e 0a 2a  other process..*
4a20: 2a 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73  * This can be us
4a30: 65 64 20 74 6f 20 72 65 6d 6f 76 65 20 61 20 73  ed to remove a s
4a40: 74 61 6c 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f  tale dot-file lo
4a50: 63 6b 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ck, for example.
4a60: 0a 2a 2a 20 49 74 20 72 65 74 75 72 6e 73 20 30  .** It returns 0
4a70: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
4a80: 6e 6f 6e 2d 7a 65 72 6f 20 66 6f 72 20 61 20 66  non-zero for a f
4a90: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ailure..**.** Th
4aa0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
4ab0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
4ac0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
4ad0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
4ae0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
4af0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
4b00: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
4b10: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
4b20: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
4b30: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
4b40: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
4b50: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
4b60: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
4b70: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
4b80: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
4b90: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
4ba0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
4bb0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
4bc0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
4bd0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
4be0: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f  .** <li> SQLITE_
4bf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 0a 2a 2a 20  IOCAP_ATOMIC.** 
4c00: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4c10: 50 5f 41 54 4f 4d 49 43 35 31 32 0a 2a 2a 20 3c  P_ATOMIC512.** <
4c20: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4c30: 5f 41 54 4f 4d 49 43 31 4b 0a 2a 2a 20 3c 6c 69  _ATOMIC1K.** <li
4c40: 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  > SQLITE_IOCAP_A
4c50: 54 4f 4d 49 43 32 4b 0a 2a 2a 20 3c 6c 69 3e 20  TOMIC2K.** <li> 
4c60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4c70: 4d 49 43 34 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51  MIC4K.** <li> SQ
4c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4c90: 43 38 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49  C8K.** <li> SQLI
4ca0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
4cb0: 36 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  6K.** <li> SQLIT
4cc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
4cd0: 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45  K.** <li> SQLITE
4ce0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
4cf0: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f  .** <li> SQLITE_
4d00: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
4d10: 44 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45  D.** <li> SQLITE
4d20: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
4d30: 4c 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  L.** </ul>.**.**
4d40: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
4d50: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
4d60: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
4d70: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
4d80: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
4d90: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
4da0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
4db0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
4dc0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
4dd0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
4de0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
4df0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
4e00: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
4e10: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
4e20: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
4e30: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
4e40: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
4e50: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
4e60: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
4e70: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
4e80: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
4e90: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
4ea0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
4eb0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
4ec0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
4ed0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
4ee0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
4ef0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
4f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4f10: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
4f20: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
4f30: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
4f40: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
4f50: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
4f60: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
4f70: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  rite()..*/.typed
4f80: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4f90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
4fa0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
4fb0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
4fc0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
4fd0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
4fe0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
4ff0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
5000: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
5010: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
5020: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
5030: 74 65 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  te_int64 iOfst);
5040: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
5050: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5060: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
5070: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69 6e   iAmt, sqlite_in
5080: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
5090: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
50a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
50b0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 69 7a 65 29  lite_int64 size)
50c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
50d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
50e0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
50f0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
5100: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
5110: 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 53 69 7a  lite_int64 *pSiz
5120: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
5130: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
5140: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
5150: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
5160: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
5170: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
5180: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
5190: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
51a0: 28 2a 78 42 72 65 61 6b 4c 6f 63 6b 29 28 73 71  (*xBreakLock)(sq
51b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
51c0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
51d0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
51e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
51f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5200: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
5210: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
5220: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
5230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
5240: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
5250: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5260: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
5270: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5280: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5290: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
52a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
52b0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
52c0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
52d0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
52e0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
52f0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5300: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5310: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
5320: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
5330: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
5340: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
5350: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5360: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
5370: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5380: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
5390: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
53a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
53b0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
53c0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
53d0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
53e0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
53f0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
5400: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
5410: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
5420: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
5430: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
5440: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
5450: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
5460: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
5470: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
5480: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56  m"..**.** The iV
5490: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
54a0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
54b0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f  may be larger fo
54c0: 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73  r future.** vers
54d0: 69 6f 6e 73 2e 20 20 73 7a 4f 73 46 69 6c 65 20  ions.  szOsFile 
54e0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
54f0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  he subclassed sq
5500: 6c 69 74 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74  lite3_file.** st
5510: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
5520: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
5530: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
5540: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
5550: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
5560: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
5570: 54 68 65 20 6e 52 65 66 20 66 69 65 6c 64 20 69  The nRef field i
5580: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 61 6e  s incremented an
5590: 64 20 64 65 63 72 65 6d 65 6e 74 65 64 20 62 79  d decremented by
55a0: 20 53 51 4c 69 74 65 20 74 6f 20 6b 65 65 70 0a   SQLite to keep.
55b0: 2a 2a 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  ** count of the 
55c0: 6e 75 6d 62 65 72 20 6f 66 20 75 73 65 72 73 20  number of users 
55d0: 6f 66 20 74 68 65 20 56 46 53 2e 20 20 54 68 69  of the VFS.  Thi
55e0: 73 20 66 69 65 6c 64 20 61 6e 64 0a 2a 2a 20 76  s field and.** v
55f0: 66 73 4d 75 74 65 78 2c 20 70 4e 65 78 74 2c 20  fsMutex, pNext, 
5600: 61 6e 64 20 70 50 72 65 76 20 61 72 65 20 74 68  and pPrev are th
5610: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e  e only fields in
5620: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
5630: 20 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74   .** structure t
5640: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
5650: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 54 68  ever modify.  Th
5660: 65 73 65 20 66 69 65 6c 64 73 20 61 72 65 20 6d  ese fields are m
5670: 6f 64 69 66 69 65 64 20 0a 2a 2a 20 77 69 74 68  odified .** with
5680: 69 6e 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 75  in an sqlite3_mu
5690: 74 65 78 5f 73 65 72 69 61 6c 69 7a 65 28 29 20  tex_serialize() 
56a0: 63 61 6c 6c 20 73 6f 20 74 68 61 74 20 75 70 64  call so that upd
56b0: 61 74 65 73 20 61 72 65 20 74 68 72 65 61 64 73  ates are threads
56c0: 61 66 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  afe..** .** The 
56d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 76 66 73 4d  sqlite3_vfs.vfsM
56e0: 75 74 65 78 20 69 73 20 61 20 6d 75 74 65 78 20  utex is a mutex 
56f0: 75 73 65 64 20 62 79 20 74 68 65 20 4f 53 20 69  used by the OS i
5700: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 74 20  nterface..** It 
5710: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 6c 79  should initially
5720: 20 62 65 20 4e 55 4c 4c 2e 20 20 53 51 4c 69 74   be NULL.  SQLit
5730: 65 20 77 69 6c 6c 20 69 6e 69 74 69 61 6c 69 7a  e will initializ
5740: 65 20 74 68 69 73 20 66 69 65 6c 64 0a 2a 2a 20  e this field.** 
5750: 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6d 75  using sqlite3_mu
5760: 74 65 78 5f 61 6c 6c 6f 63 61 74 65 28 29 20 75  tex_allocate() u
5770: 70 6f 6e 20 66 69 72 73 74 20 75 73 65 20 6f 66  pon first use of
5780: 20 74 68 65 20 61 64 61 70 74 6f 72 0a 2a 2a 20   the adaptor.** 
5790: 62 79 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  by sqlite3_open_
57a0: 76 32 28 29 20 61 6e 64 20 77 69 6c 6c 20 64 65  v2() and will de
57b0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d 75 74  allocate the mut
57c0: 65 78 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ex when the.** l
57d0: 61 73 74 20 75 73 65 72 20 63 6c 6f 73 65 73 2e  ast user closes.
57e0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
57f0: 2c 20 76 66 73 4d 75 74 65 78 20 77 69 6c 6c 20  , vfsMutex will 
5800: 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20  be allocated.** 
5810: 77 68 65 6e 20 6e 52 65 66 20 74 72 61 6e 73 69  when nRef transi
5820: 74 69 6f 6e 73 20 66 72 6f 6d 20 30 20 74 6f 20  tions from 0 to 
5830: 31 20 61 6e 64 20 77 69 6c 6c 20 62 65 20 64 65  1 and will be de
5840: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 0a 2a  allocated when.*
5850: 2a 20 6e 52 65 66 20 74 72 61 6e 73 69 74 69 6f  * nRef transitio
5860: 6e 73 20 66 72 6f 6d 20 31 20 74 6f 20 30 2e 0a  ns from 1 to 0..
5870: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
5880: 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65   vfs modules are
5890: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
58a0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
58b0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 61 6e  .** the pNext an
58c0: 64 20 70 50 72 65 76 20 70 6f 69 6e 74 65 72 73  d pPrev pointers
58d0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
58e0: 72 65 67 69 73 74 65 72 5f 76 66 73 28 29 5d 0a  register_vfs()].
58f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
5900: 75 6e 72 65 67 69 73 74 65 72 5f 76 66 73 28 29  unregister_vfs()
5910: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
5920: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
5930: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
5940: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
5950: 69 74 65 33 5f 66 69 6e 64 5f 76 66 73 28 29 5d  ite3_find_vfs()]
5960: 20 73 65 61 72 63 68 65 73 20 74 68 65 0a 2a 2a   searches the.**
5970: 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   list..**.** The
5980: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
5990: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
59a0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
59b0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
59c0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
59d0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
59e0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
59f0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
5a00: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
5a10: 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20  e string passed 
5a20: 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73  to.** xOpen() is
5a30: 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65   a full pathname
5a40: 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79   as generated by
5a50: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
5a60: 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65   and.** that the
5a70: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
5a80: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
5a90: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
5aa0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
5ab0: 20 20 53 6f 20 74 68 65 20 73 71 6c 69 74 65 33    So the sqlite3
5ac0: 5f 66 69 6c 65 20 63 61 6e 20 73 74 6f 72 65 20  _file can store 
5ad0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
5ae0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
5af0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
5b00: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
5b10: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
5b20: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  n..**.** The fla
5b30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
5b40: 4f 70 65 6e 28 29 20 69 73 20 61 20 63 6f 70 79  Open() is a copy
5b50: 20 6f 66 20 74 68 65 20 66 6c 61 67 73 20 61 72   of the flags ar
5b60: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
5b70: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
5b80: 20 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   If sqlite3_open
5b90: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
5ba0: 65 6e 31 36 28 29 0a 2a 2a 20 69 73 20 75 73 65  en16().** is use
5bb0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 73  d, then flags is
5bc0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5bd0: 44 57 52 49 54 45 20 7c 20 53 51 4c 49 54 45 5f  DWRITE | SQLITE_
5be0: 4f 50 45 4e 5f 43 52 45 41 54 45 2e 0a 2a 2a 20  OPEN_CREATE..** 
5bf0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
5c00: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
5c10: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
5c20: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
5c30: 69 6e 63 6c 75 64 65 20 53 51 4c 49 54 45 5f 4f  include SQLITE_O
5c40: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 2e 20 20 4f  PEN_READONLY.  O
5c50: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
5c60: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a  utFlags may be.*
5c70: 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  * set..** .** SQ
5c80: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
5c90: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
5ca0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
5cb0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
5cc0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
5cd0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
5ce0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a  ing opened:.** .
5cf0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
5d00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
5d10: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
5d20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
5d30: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
5d40: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
5d50: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
5d60: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
5d70: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
5d80: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
5d90: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
5da0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
5db0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
5dc0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  RNAL].** </ul>.*
5dd0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
5de0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
5df0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
5e00: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
5e10: 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 65  o.** changes the
5e20: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
5e30: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
5e40: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
5e50: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
5e60: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
5e70: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
5e80: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d  y or rollback, m
5e90: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
5ea0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
5eb0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
5ec0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
5ed0: 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a 2a 20   journal are.** 
5ee0: 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20 41  also a no-op.  A
5ef0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
5f00: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 72  ad the journal r
5f10: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49 4f 45  eturn SQLITE_IOE
5f20: 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20 69 6d  RR..** Or the im
5f30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
5f40: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 65  ht recognize the
5f50: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
5f60: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e   will.** be doin
5f70: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
5f80: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
5f90: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
5fa0: 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e 64 20  om order.** and 
5fb0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
5fc0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
5fd0: 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c  ngly..** .** SQL
5fe0: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
5ff0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
6000: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
6010: 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65   the xOpen.** me
6020: 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  thod:.** .** <ul
6030: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6040: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6050: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
6060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6070: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
6080: 2a 20 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  * .** The [SQLIT
6090: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
60a0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
60b0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
60c0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
60d0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
60e0: 2e 20 20 54 68 69 73 20 77 69 6c 6c 20 61 6c 77  .  This will alw
60f0: 61 79 73 20 62 65 20 73 65 74 20 66 6f 72 20 54  ays be set for T
6100: 45 4d 50 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  EMP .** database
6110: 73 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 73 20 61  s and journals a
6120: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61  nd for subjourna
6130: 6c 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51  ls.  The .** [SQ
6140: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6150: 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  IVE] flag means 
6160: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
6170: 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72  be opened.** for
6180: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
6190: 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73  s.  This flag is
61a0: 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c   set for all fil
61b0: 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72  es except.** for
61c0: 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
61d0: 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a 20  se file..** .** 
61e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  The sqlite3_file
61f0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
6200: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
6210: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 4f  rgument to.** xO
6220: 70 65 6e 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  pen is allocated
6230: 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
6240: 20 78 4f 70 65 6e 20 6a 75 73 74 20 66 69 6c 6c   xOpen just fill
6250: 73 20 69 74 20 69 6e 2e 20 20 54 68 65 0a 2a 2a  s it in.  The.**
6260: 20 63 61 6c 6c 65 72 20 61 6c 6c 6f 63 61 74 65   caller allocate
6270: 73 20 61 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 73  s a minimum of s
6280: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 66 6f  zOsFile bytes fo
6290: 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  r the sqlite3_fi
62a0: 6c 65 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 2e  le.** structure.
62b0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67  .** .** The flag
62c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
62d0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 30  ccess() may be 0
62e0: 20 28 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68   (to test for th
62f0: 65 0a 2a 2a 20 65 78 69 73 74 61 6e 63 65 20 6f  e.** existance o
6300: 66 20 61 20 66 69 6c 65 29 20 6f 72 20 53 51 4c  f a file) or SQL
6310: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
6320: 52 49 54 45 20 74 6f 20 74 65 73 74 20 74 6f 20  RITE to test to 
6330: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
6340: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
6350: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 53 51   writable, or SQ
6360: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
6370: 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 74 65 73 74 20  ONLY.** to test 
6380: 74 6f 20 73 65 65 20 69 66 20 61 20 66 69 6c 65  to see if a file
6390: 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20   is read-only.  
63a0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
63b0: 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e  a .** directory.
63c0: 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77  .** .** SQLite w
63d0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
63e0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
63f0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66  athname+1 byte f
6400: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74  or.** the output
6410: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65   buffers for xGe
6420: 74 54 65 6d 70 4e 61 6d 65 20 61 6e 64 20 78 46  tTempName and xF
6430: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 0a 2a 2a 20  ullPathname..** 
6440: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
6450: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
6460: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
6470: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
6480: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
6490: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
64a0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
64b0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
64c0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
64d0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
64e0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
64f0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
6500: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
6510: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
6520: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
6530: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
6540: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
6550: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
6560: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
6570: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
6580: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
6590: 6e 65 73 73 20 67 65 6e 65 72 61 74 65 64 2e 20  ness generated. 
65a0: 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29   The.** xSleep()
65b0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 20 74 68   method cause th
65c0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
65d0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
65e0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
65f0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
6600: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
6610: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
6620: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
6630: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
6640: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
6650: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a  rrent date and.*
6660: 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  * time..*/.typed
6670: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6680: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
6690: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
66a0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
66b0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
66c0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
66d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
66e0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
66f0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
6700: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
6710: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
6720: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
6730: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
6740: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
6750: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
6760: 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
6770: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
6780: 75 6d 62 65 72 20 6f 66 20 72 65 66 65 72 65 6e  umber of referen
6790: 63 65 73 20 74 6f 20 74 68 69 73 20 73 74 72 75  ces to this stru
67a0: 63 74 75 72 65 20 2a 2f 0a 20 20 73 71 6c 69 74  cture */.  sqlit
67b0: 65 33 5f 6d 75 74 65 78 20 2a 76 66 73 4d 75 74  e3_mutex *vfsMut
67c0: 65 78 3b 20 2f 2a 20 41 20 6d 75 74 65 78 20 66  ex; /* A mutex f
67d0: 6f 72 20 74 68 69 73 20 56 46 53 20 2a 2f 0a 20  or this VFS */. 
67e0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
67f0: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
6800: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
6810: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
6820: 73 20 2a 70 50 72 65 76 3b 20 20 20 20 20 20 2f  s *pPrev;      /
6830: 2a 20 50 72 65 76 69 6f 75 73 20 72 65 67 69 73  * Previous regis
6840: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
6850: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6860: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
6870: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
6880: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
6890: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
68a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 70 70            /* App
68b0: 6c 69 63 61 74 69 6f 6e 20 63 6f 6e 74 65 78 74  lication context
68c0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
68d0: 6e 29 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74  n)(void *pAppDat
68e0: 61 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  a, const char *z
68f0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
6900: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
6910: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
6920: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
6930: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
6940: 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c  (void *pAppData,
6950: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
6960: 6d 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  me);.  int (*xAc
6970: 63 65 73 73 29 28 76 6f 69 64 20 2a 70 41 70 70  cess)(void *pApp
6980: 44 61 74 61 2c 20 63 6f 6e 73 74 20 63 68 61 72  Data, const char
6990: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
69a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  gs);.  int (*xGe
69b0: 74 54 65 6d 70 4e 61 6d 65 29 28 76 6f 69 64 20  tTempName)(void 
69c0: 2a 70 41 70 70 44 61 74 61 2c 20 63 68 61 72 20  *pAppData, char 
69d0: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
69e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 76  xFullPathname)(v
69f0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63  oid *pAppData, c
6a00: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6a10: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
6a20: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
6a30: 29 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61  )(void *pAppData
6a40: 2c 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  , char *zFilenam
6a50: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
6a60: 45 72 72 6f 72 29 28 76 6f 69 64 2a 2c 20 69 6e  Error)(void*, in
6a70: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
6a80: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
6a90: 2a 28 2a 78 44 6c 53 79 6d 29 28 76 6f 69 64 2a  *(*xDlSym)(void*
6aa0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
6ab0: 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28  ymbol);.  void (
6ac0: 2a 78 44 6c 63 6c 6f 73 65 29 28 76 6f 69 64 2a  *xDlclose)(void*
6ad0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
6ae0: 6f 6d 6e 65 73 73 29 28 76 6f 69 64 20 2a 70 41  omness)(void *pA
6af0: 70 70 44 61 74 61 2c 20 69 6e 74 20 6e 42 79 74  ppData, int nByt
6b00: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
6b10: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
6b20: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20  void *pAppData, 
6b30: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
6b40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
6b50: 65 6e 74 54 69 6d 65 29 28 76 6f 69 64 20 2a 70  entTime)(void *p
6b60: 41 70 70 44 61 74 61 2c 20 64 6f 75 62 6c 65 2a  AppData, 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 45 6e 61  ** CAPI3REF: Ena
6c00: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
6c10: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
6c20: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  odes.**.** This 
6c30: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
6c40: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
6c50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
6c60: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
6c70: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
6c80: 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65  eature..** By de
6c90: 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50  fault, SQLite AP
6ca0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
6cb0: 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36  n one of only 26
6cc0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
6cd0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
6ce0: 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78  codes].  When ex
6cf0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
6d00: 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  des.** are enabl
6d10: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
6d20: 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72  ne, the repetoir
6d30: 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65  e of result code
6d40: 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68  s can be.** much
6d50: 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20   larger and can 
6d60: 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76  (hopefully) prov
6d70: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
6d80: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
6d90: 20 61 62 6f 75 74 20 74 68 65 20 63 61 75 73 65   about the cause
6da0: 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a   of an error..**
6db0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
6dc0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f  rgument is a boo
6dd0: 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20  lean value that 
6de0: 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72  turns extended r
6df0: 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f  esult.** codes o
6e00: 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65  n and off.  Exte
6e10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
6e20: 73 20 61 72 65 20 6f 66 66 20 62 79 20 64 65 66  s are off by def
6e30: 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b  ault for.** back
6e40: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
6e50: 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76  ity with older v
6e60: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
6e70: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
6e80: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
6e90: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
6ea0: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
6eb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
6ec0: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
6ed0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
6ee0: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
6ef0: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
6f00: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
6f10: 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63  integer key.** c
6f20: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64  alled the "rowid
6f30: 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ". The rowid is 
6f40: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
6f50: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
6f60: 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  d.** column name
6f70: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
6f80: 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68   _ROWID_.  If th
6f90: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
6fa0: 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20  lumn of.** type 
6fb0: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
6fc0: 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f  KEY then that co
6fd0: 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20  lumn is another 
6fe0: 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  an alias for the
6ff0: 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  .** rowid..**.**
7000: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
7010: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
7020: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
7030: 6e 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a  nt INSERT into.*
7040: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
7050: 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
7060: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65   connection give
7070: 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a  n in the first .
7080: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
7090: 20 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65   no inserts have
70a0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
70b0: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 0a  n this database.
70c0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  ** connection, z
70d0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
70e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
70f0: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
7100: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
7110: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
7120: 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72  he.** inserted r
7130: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
7140: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
7150: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
7160: 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e  igger.** is runn
7170: 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74  ing.  But once t
7180: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
7190: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
71a0: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
71b0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
71c0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
71d0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
71e0: 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72  before the.** tr
71f0: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2f 0a  igger fired..*/.
7200: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
7210: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
7220: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
7230: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
7240: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
7250: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
7260: 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ified.**.** This
7270: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
7280: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
7290: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
72a0: 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
72b0: 2a 2a 20 28 6f 72 20 69 6e 73 65 72 74 65 64 20  ** (or inserted 
72c0: 6f 72 20 64 65 6c 65 74 65 64 29 20 62 79 20 74  or deleted) by t
72d0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 53  he most recent S
72e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f  QL statement.  O
72f0: 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  nly.** changes t
7300: 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
7310: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
7320: 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
7330: 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73  , or.** DELETE s
7340: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
7350: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
7360: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
7370: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61  by.** triggers a
7380: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
7390: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
73a0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
73b0: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
73c0: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
73d0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
73e0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
73f0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
7400: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57  riggers..**.** W
7410: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
7420: 66 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  f a trigger, the
7430: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
7440: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
7450: 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f   be.** called to
7460: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
7470: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
7480: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
7490: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
74a0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
74b0: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
74c0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
74d0: 62 6f 64 79 20 6f 66 20 74 68 65 20 74 72 69 67  body of the trig
74e0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63  ger..**.** All c
74f0: 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
7500: 65 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79  ed, even if they
7510: 20 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f   were later undo
7520: 6e 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42  ne by a.** ROLLB
7530: 41 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 45  ACK or ABORT.  E
7540: 78 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61  xcept, changes a
7550: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
7560: 72 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64  reating and.** d
7570: 72 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61  ropping tables a
7580: 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
7590: 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62  **.** If a callb
75a0: 61 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ack invokes [sql
75b0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
75c0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
75d0: 20 72 65 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a   recursively,.**
75e0: 20 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65   then the change
75f0: 73 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20  s in the inner, 
7600: 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61  recursive call a
7610: 72 65 20 63 6f 75 6e 74 65 64 20 74 6f 67 65 74  re counted toget
7620: 68 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  her.** with the 
7630: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f  changes in the o
7640: 75 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  uter call..**.**
7650: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
7660: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
7670: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
7680: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
7690: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
76a0: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
76b0: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
76c0: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
76d0: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
76e0: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
76f0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
7700: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
7710: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
7720: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
7730: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
7740: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
7750: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
7760: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
7770: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
7780: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
7790: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
77a0: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
77b0: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
77c0: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
77d0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
77e0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
77f0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
7800: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
7810: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
7820: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2f 0a 69 6e  " instead..*/.in
7830: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
7840: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
7850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
7860: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
7870: 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a  ws Modified.***.
7880: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
7890: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
78a0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
78b0: 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 20 62  rows that have b
78c0: 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  een.** modified 
78d0: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  by INSERT, UPDAT
78e0: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
78f0: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
7900: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
7910: 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20  .** was opened. 
7920: 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 55 50  This includes UP
7930: 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e 64  DATE, INSERT and
7940: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
7950: 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a 20 61  ts executed.** a
7960: 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  s part of trigge
7970: 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20  r programs. All 
7980: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
7990: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
79a0: 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
79b0: 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
79c0: 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
79d0: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
79e0: 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61   handle is.** pa
79f0: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
7a00: 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
7a10: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 73 65 28 29  lite3_finalise()
7a20: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
7a30: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
7a40: 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65 72 66  change()] interf
7a50: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ace..**.** SQLit
7a60: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
7a70: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
7a80: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
7a90: 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
7aa0: 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
7ab0: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
7ac0: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
7ad0: 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
7ae0: 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
7af0: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
7b00: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
7b10: 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74   elements form t
7b20: 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
7b30: 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f  use of.** this o
7b40: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
7b50: 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f   change count fo
7b60: 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  r "DELETE FROM t
7b70: 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a  able" will be.**
7b80: 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73   zero regardless
7b90: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
7ba0: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
7bb0: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  were originally 
7bc0: 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e  in the.** table.
7bd0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
7be0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
7bf0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
7c00: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
7c10: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
7c20: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
7c30: 65 61 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ead..*/.int sqli
7c40: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
7c50: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
7c60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
7c70: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
7c80: 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
7c90: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
7ca0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
7cb0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
7cc0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
7cd0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
7ce0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
7cf0: 70 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73  portunity.  This
7d00: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
7d10: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
7d20: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
7d30: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
7d40: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
7d50: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
7d60: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
7d70: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
7d80: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
7d90: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
7da0: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
7db0: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
7dc0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
7dd0: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
7de0: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
7df0: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
7e00: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
7e10: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
7e20: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
7e30: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
7e40: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
7e50: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61  outine with a da
7e60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7e70: 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  n that.** is clo
7e80: 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
7e90: 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
7ea0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
7eb0: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
7ec0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
7ed0: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
7ee0: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
7ef0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
7f00: 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  ]..** If an inte
7f10: 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f  rrupted operatio
7f20: 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20  n was an update 
7f30: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
7f40: 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
7f50: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
7f60: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
7f70: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
7f80: 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75  olled.** back au
7f90: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a  tomatically..*/.
7fa0: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
7fb0: 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
7fc0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7fd0: 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
7fe0: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
7ff0: 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
8000: 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
8010: 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ns return true i
8020: 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75  f the given inpu
8030: 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73  t string compris
8040: 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  es.** one or mor
8050: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  e complete SQL s
8060: 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74  tatements. For t
8070: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
8080: 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74  ete() call,.** t
8090: 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  he parameter mus
80a0: 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69  t be a nul-termi
80b0: 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
80c0: 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74  ng. For.** sqlit
80d0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c  e3_complete16(),
80e0: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
80f0: 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f  d machine byte o
8100: 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69  rder UTF-16 stri
8110: 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65  ng.** is require
8120: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
8130: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
8140: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
8150: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
8160: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
8170: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
8180: 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e  ed text forms on
8190: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
81a0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
81b0: 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  s or.** if addit
81c0: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
81d0: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
81e0: 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65  ding the stateme
81f0: 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  nts into.** SQLi
8200: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
8210: 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  The algorithm is
8220: 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65   simple.  If the
8230: 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20   .** last token 
8240: 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65  other than space
8250: 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69  s and comments i
8260: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74  s a semicolon, t
8270: 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74  hen return .** t
8280: 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20  rue.  Actually, 
8290: 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  the algorithm is
82a0: 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63   a little more c
82b0: 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20  omplicated than 
82c0: 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  that.** in order
82d0: 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72   to deal with tr
82e0: 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20  iggers, but the 
82f0: 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68  basic idea is th
8300: 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20  e same:  the.** 
8310: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
8320: 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73   complete unless
8330: 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65   it ends in a se
8340: 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  micolon..*/.int 
8350: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
8360: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
8370: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
8380: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
8390: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
83a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
83b0: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
83c0: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
83d0: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
83e0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
83f0: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
8400: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8410: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
8420: 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65  voked.** wheneve
8430: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
8440: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
8450: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
8460: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
8470: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
8480: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
8490: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
84a0: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
84b0: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
84c0: 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65  .** (or sometime
84d0: 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  s [SQLITE_IOERR_
84e0: 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20  BLOCKED]).** is 
84f0: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
8500: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
8510: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
8520: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
8530: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
8540: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
8550: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  * callback will 
8560: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
8570: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  two arguments.  
8580: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
8590: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
85a0: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
85b0: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
85c0: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
85d0: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
85e0: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  nt to this routi
85f0: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ne.  The second 
8600: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
8610: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68  he handler is th
8620: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
8630: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
8640: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
8650: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
8660: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
8670: 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  nt. If the.** bu
8680: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
8690: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
86a0: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
86b0: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
86c0: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
86d0: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
86e0: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
86f0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
8700: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
8710: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
8720: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
8730: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
8740: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
8750: 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20   to open the.** 
8760: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
8770: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
8780: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
8790: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
87a0: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
87b0: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
87c0: 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77  tee that.** it w
87d0: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
87e0: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
87f0: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a  k contention..**
8800: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
8810: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
8820: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
8830: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
8840: 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f  t in.** a deadlo
8850: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75  ck, it will retu
8860: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
8870: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e   instead..** Con
8880: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
8890: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
88a0: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
88b0: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
88c0: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
88d0: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
88e0: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
88f0: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
8900: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
8910: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
8920: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
8930: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
8940: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
8950: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
8960: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
8970: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
8980: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
8990: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
89a0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
89b0: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
89c0: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
89d0: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
89e0: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
89f0: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
8a00: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
8a10: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
8a20: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
8a30: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
8a40: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
8a50: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
8a60: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
8a70: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
8a80: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
8a90: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
8aa0: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
8ab0: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
8ac0: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
8ad0: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
8ae0: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
8af0: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
8b00: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
8b10: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
8b20: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8b30: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
8b40: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
8b50: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
8b60: 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69  ED] when.** SQLi
8b70: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
8b80: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
8b90: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
8ba0: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
8bb0: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
8bc0: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
8bd0: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
8be0: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
8bf0: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
8c00: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
8c10: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
8c20: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
8c30: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
8c40: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
8c50: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
8c60: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
8c70: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
8c80: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
8c90: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
8ca0: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
8cb0: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
8cc0: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
8cd0: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
8ce0: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
8cf0: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
8d00: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
8d10: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
8d20: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
8d30: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
8d40: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
8d50: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
8d60: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
8d70: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
8d80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
8d90: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
8da0: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
8db0: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
8dc0: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
8dd0: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
8de0: 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
8df0: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e  ref="http://www.
8e00: 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72  sqlite.org/cvstr
8e10: 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
8e20: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
8e30: 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
8e40: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
8e50: 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
8e60: 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
8e70: 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
8e80: 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
8e90: 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69  ant..**..** Sqli
8ea0: 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74  te is re-entrant
8eb0: 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61  , so the busy ha
8ec0: 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20  ndler may start 
8ed0: 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a  a new query. .**
8ee0: 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61   (It is not clea
8ef0: 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75  r why anyone wou
8f00: 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f  ld every want to
8f10: 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74   do this, but it
8f20: 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20  .** is allowed, 
8f30: 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74  in theory.)  But
8f40: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
8f50: 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20  r may not close 
8f60: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
8f70: 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61    Closing the da
8f80: 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75  tabase from a bu
8f90: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  sy handler will 
8fa0: 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20  delete .** data 
8fb0: 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66  structures out f
8fc0: 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78  rom under the ex
8fd0: 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e  ecuting query an
8fe0: 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61  d will .** proba
8ff0: 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20  bly result in a 
9000: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
9010: 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74  lt or other runt
9020: 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  ime error..**.**
9030: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
9040: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
9050: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
9060: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
9070: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9080: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
9090: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
90a0: 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ears any previou
90b0: 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  s one..** Note t
90c0: 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
90d0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
90e0: 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73  t()] will also s
90f0: 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74  et or clear.** t
9100: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
9110: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9120: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
9130: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
9140: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
9150: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9160: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
9170: 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73  meout.**.** This
9180: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
9190: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74 68 61  busy handler tha
91a0: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77  t sleeps for a w
91b0: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74  hile when a.** t
91c0: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
91d0: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c   The handler wil
91e0: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
91f0: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a   times until .**
9200: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
9210: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
9220: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65  leeping have bee
9230: 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 0a 2a  n done.  After.*
9240: 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  * "ms" milliseco
9250: 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
9260: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
9270: 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20  urns 0 which.** 
9280: 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
9290: 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
92a0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
92b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
92c0: 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
92d0: 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
92e0: 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
92f0: 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
9300: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
9310: 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
9320: 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
9330: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
9340: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
9350: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
9360: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9370: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9380: 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f  nection.  If ano
9390: 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
93a0: 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a  r was defined  .
93b0: 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  ** (using [sqlit
93c0: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
93d0: 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
93e0: 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
93f0: 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
9400: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
9410: 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74   cleared..*/.int
9420: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
9430: 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
9440: 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
9450: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
9460: 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
9470: 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
9480: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6e 65  es.**.** This ne
9490: 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  xt routine is a 
94a0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
94b0: 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69  per around [sqli
94c0: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2a 20  te3_exec()]..** 
94d0: 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  Instead of invok
94e0: 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 70 6c  ing a user-suppl
94f0: 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  ied callback for
9500: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
9510: 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 69 73  .** result, this
9520: 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d 62 65   routine remembe
9530: 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74  rs each row of t
9540: 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d 65 6d  he result in mem
9550: 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
9560: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
9570: 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 72 65  lloc()], then re
9580: 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 68 65  turns all of the
9590: 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 74 68   result after th
95a0: 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 20 66  e.** query has f
95b0: 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  inished. .**.** 
95c0: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 73  As an example, s
95d0: 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 72 79  uppose the query
95e0: 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 74 68   result where th
95f0: 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20  is table:.**.** 
9600: 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
9610: 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
9620: 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
9630: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
9640: 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
9650: 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
9660: 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
9670: 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
9680: 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
9690: 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  | 21.** </pre>.*
96a0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
96b0: 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61  argument were &a
96c0: 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74  zResult then aft
96d0: 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  er the function 
96e0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73  returns.** azRes
96f0: 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ult will contain
9700: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   the following d
9710: 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ata:.**.** <pre>
9720: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9730: 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  ult[0] = "Name";
9740: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9750: 75 6c 74 5b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  ult[1] = "Age";.
9760: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
9770: 6c 74 5b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  lt[2] = "Alice";
9780: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
9790: 75 6c 74 5b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  ult[3] = "43";.*
97a0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
97b0: 74 5b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  t[4] = "Bob";.**
97c0: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
97d0: 5b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  [5] = "28";.**  
97e0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 36        azResult[6
97f0: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
9800: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9810: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
9820: 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63  pre>.**.** Notic
9830: 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  e that there is 
9840: 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f 66 20  an extra row of 
9850: 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e 67 20  data containing 
9860: 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65  the column.** he
9870: 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 65 20  aders.  But the 
9880: 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 61 6c  *nrow return val
9890: 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e 20 20  ue is still 3.  
98a0: 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73  *ncolumn is.** s
98b0: 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 65 6e  et to 2.  In gen
98c0: 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 65 72  eral, the number
98d0: 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 65 72   of values inser
98e0: 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 75 6c  ted into azResul
98f0: 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 28 2a  t.** will be ((*
9900: 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e 63 6f  nrow) + 1)*(*nco
9910: 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  lumn)..**.** Aft
9920: 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
9930: 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
9940: 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
9950: 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
9960: 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 72 65   .** pass the re
9970: 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e 74 65  sult data pointe
9980: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
9990: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
99a0: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73  er to .** releas
99b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
99c0: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e  t was malloc-ed.
99d0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
99e0: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
99f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9a00: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 61 6c  happens, the cal
9a10: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ling function mu
9a20: 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
9a30: 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ll .** [sqlite3_
9a40: 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
9a50: 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 65 33  .  Only [sqlite3
9a60: 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
9a70: 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
9a80: 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  e .** the memory
9a90: 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
9aa0: 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
9ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
9ac0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
9ad0: 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 6f 6d  the same as from
9ae0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
9af0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
9b00: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
9b10: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
9b20: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
9b30: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
9b40: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
9b50: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
9b60: 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f 0a 20  be executed */. 
9b70: 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74 70   char ***resultp
9b80: 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  ,       /* Resul
9b90: 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 20 63  t written to a c
9ba0: 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 74 68  har *[]  that th
9bb0: 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a  is points to */.
9bc0: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
9bd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
9be0: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
9bf0: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
9c00: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
9c10: 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  ,          /* Nu
9c20: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
9c30: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
9c40: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
9c50: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
9c60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
9c70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
9c80: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
9c90: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
9ca0: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
9cb0: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
9cc0: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
9cd0: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
9ce0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
9cf0: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
9d00: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
9d10: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
9d20: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
9d30: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
9d40: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
9d50: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
9d60: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
9d70: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
9d80: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
9d90: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
9da0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
9db0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
9dc0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
9dd0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
9de0: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
9df0: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
9e00: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
9e10: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
9e20: 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
9e30: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
9e40: 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
9e50: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
9e60: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9e70: 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
9e80: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
9e90: 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
9ea0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
9eb0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
9ec0: 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
9ed0: 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
9ee0: 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
9ef0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
9f00: 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
9f10: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
9f20: 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
9f30: 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
9f40: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
9f50: 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
9f60: 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
9f70: 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e 6f  t parameter.  No
9f80: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
9f90: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
9fa0: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
9fb0: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
9fc0: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
9fd0: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
9fe0: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
9ff0: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
a000: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
a010: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
a020: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
a030: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
a040: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
a050: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
a060: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
a070: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
a080: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
a090: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
a0a0: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
a0b0: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
a0c0: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
a0d0: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
a0e0: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
a0f0: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
a100: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
a110: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
a120: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
a130: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
a140: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
a150: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
a160: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
a170: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
a180: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
a190: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
a1a0: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
a1b0: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
a1c0: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
a1d0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
a1e0: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
a1f0: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
a200: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
a210: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
a220: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
a230: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
a240: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
a250: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
a260: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
a270: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
a280: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
a290: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
a2a0: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
a2b0: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
a2c0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
a2d0: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
a2e0: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
a2f0: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
a300: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
a310: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
a320: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
a330: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
a340: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
a350: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
a360: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
a370: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
a380: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 20  .** is are "%q" 
a390: 61 6e 64 20 22 25 51 22 20 6f 70 74 69 6f 6e 73  and "%Q" options
a3a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
a3b0: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
a3c0: 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
a3d0: 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
a3e0: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
a3f0: 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
a400: 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
a410: 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
a420: 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
a430: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
a440: 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
a450: 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
a460: 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
a470: 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
a480: 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
a490: 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
a4a0: 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
a4b0: 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
a4c0: 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
a4d0: 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
a4e0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73  * For example, s
a4f0: 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61  o some string va
a500: 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20  riable contains 
a510: 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
a520: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
a530: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
a540: 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
a550: 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
a560: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
a570: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
a580: 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
a590: 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
a5a0: 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
a5b0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
a5c0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
a5d0: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
a5e0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
a5f0: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
a600: 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
a610: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
a620: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
a630: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
a640: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
a650: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
a660: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
a670: 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
a680: 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
a690: 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
a6a0: 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
a6b0: 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
a6c0: 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
a6d0: 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
a6e0: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
a6f0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
a700: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
a710: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
a720: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
a730: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
a740: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
a750: 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
a760: 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
a770: 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
a780: 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
a790: 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
a7a0: 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
a7b0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
a7c0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
a7d0: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
a7e0: 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
a7f0: 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
a800: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
a810: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
a820: 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
a830: 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
a840: 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
a850: 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73  al rule you.** s
a860: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65  hould always use
a870: 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
a880: 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
a890: 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
a8a0: 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e  ing .** literal.
a8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70  .**.** The %Q op
a8c0: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
a8d0: 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
a8e0: 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
a8f0: 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
a900: 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
a910: 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
a920: 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   Or if the param
a930: 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75  eter in the argu
a940: 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20  ment.** list is 
a950: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
a960: 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
a970: 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
a980: 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a  without single.*
a990: 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  * quotes) in pla
a9a0: 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
a9b0: 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
a9c0: 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
a9d0: 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
a9e0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
a9f0: 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
aa00: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
aa10: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
aa20: 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
aa30: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
aa40: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
aa50: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
aa60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
aa70: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
aa80: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
aa90: 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
aaa0: 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
aab0: 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
aac0: 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
aad0: 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
aae0: 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
aaf0: 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
ab00: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61   pointer..*/.cha
ab10: 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
ab20: 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
ab30: 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
ab40: 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
ab50: 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
ab60: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
ab70: 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
ab80: 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
ab90: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
aba0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
abb0: 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
abc0: 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
abd0: 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
abe0: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
abf0: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
ac00: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
ac10: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
ac20: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 20 54 68 65  tion needs.  The
ac30: 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
ac40: 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
ac50: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ac60: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
ac70: 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  es the malloc(),
ac80: 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e   realloc().** an
ac90: 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
aca0: 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
acb0: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 6f  d C library.  Ho
acc0: 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51  wever, if .** SQ
acd0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ace0: 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77   with the follow
acf0: 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73  ing C preprocess
ad00: 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c  or macro.**.** <
ad10: 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49  blockquote> SQLI
ad20: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
ad30: 4c 4c 4f 43 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63  LLOCATION </bloc
ad40: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68  kquote>.**.** th
ad50: 65 6e 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61  en no implementa
ad60: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
ad70: 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
ad80: 6e 65 73 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  nes by.** SQLite
ad90: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
ada0: 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  on that links ag
adb0: 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
adc0: 2a 2a 20 65 78 70 65 63 74 65 64 20 74 6f 20 70  ** expected to p
add0: 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69  rovide its own i
ade0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
adf0: 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
ae00: 6d 61 6c 6c 6f 63 28 75 6e 73 69 67 6e 65 64 20  malloc(unsigned 
ae10: 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
ae20: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
ae30: 2a 2c 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 29  *, unsigned int)
ae40: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
ae50: 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
ae60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
ae70: 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
ae80: 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49  atistics.**.** I
ae90: 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 74 68  n addition to th
aea0: 65 20 62 61 73 69 63 20 74 68 72 65 65 20 61 6c  e basic three al
aeb0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
aec0: 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  s .** [sqlite3_m
aed0: 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
aee0: 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
aef0: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
af00: 28 29 5d 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ()],.** the memo
af10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
af20: 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64  bsystem included
af30: 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 65   with the SQLite
af40: 0a 2a 2a 20 73 6f 75 72 63 65 73 20 70 72 6f 76  .** sources prov
af50: 69 64 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ides the interfa
af60: 63 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e  ces shown below.
af70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
af80: 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 72 6f   of these two ro
af90: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 74  utines returns t
afa0: 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  he amount of mem
afb0: 6f 72 79 20 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  ory .** currentl
afc0: 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
afd0: 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
afe0: 66 72 65 65 64 29 2e 20 20 54 68 65 20 73 65 63  freed).  The sec
aff0: 6f 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ond.** returns t
b000: 68 65 20 6c 61 72 67 65 73 74 20 69 6e 73 74 61  he largest insta
b010: 6e 74 61 6e 65 6f 75 73 20 61 6d 6f 75 6e 74 20  ntaneous amount 
b020: 6f 66 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  of outstanding.*
b030: 2a 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 68  * memory.  The h
b040: 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73  ighwater mark is
b050: 20 72 65 73 65 74 20 69 66 20 74 68 65 20 61 72   reset if the ar
b060: 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 72 75  gument is.** tru
b070: 65 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  e.  The SQLite c
b080: 6f 72 65 20 64 6f 65 73 20 6e 6f 74 20 75 73 65  ore does not use
b090: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
b0a0: 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 6e 64   routines.** and
b0b0: 20 73 6f 20 74 68 65 79 20 64 6f 20 6e 6f 74 20   so they do not 
b0c0: 68 61 76 65 20 74 6f 20 62 65 20 69 6d 70 6c 65  have to be imple
b0d0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 61 70  mented by the ap
b0e0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 69 66 20  plication.** if 
b0f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
b100: 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 69 73  RY_ALLOCATION is
b110: 20 64 65 66 69 6e 65 64 2e 20 20 54 68 65 73 65   defined.  These
b120: 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
b130: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
b140: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
b150: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 64 69  subsystem for di
b160: 61 67 6e 6f 73 74 69 63 0a 2a 2a 20 70 75 72 70  agnostic.** purp
b170: 6f 73 65 73 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  oses..*/.sqlite3
b180: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
b190: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
b1a0: 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
b1b0: 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
b1c0: 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
b1d0: 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
b1e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
b1f0: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c  ry Allocation Al
b200: 61 72 6d 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  arms.**.** The [
b210: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
b220: 6c 61 72 6d 5d 20 72 6f 75 74 69 6e 65 20 69 73  larm] routine is
b230: 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
b240: 72 0a 2a 2a 20 61 20 63 61 6c 6c 62 61 63 6b 20  r.** a callback 
b250: 6f 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  on memory alloca
b260: 74 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a  tion events..**.
b270: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
b280: 72 65 67 69 73 74 65 72 73 20 6f 72 20 63 6c 65  registers or cle
b290: 61 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 73 20  ars a callbacks 
b2a0: 74 68 61 74 20 66 69 72 65 73 20 77 68 65 6e 0a  that fires when.
b2b0: 2a 2a 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** the amount of
b2c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
b2d0: 64 20 65 78 63 65 65 64 73 20 69 54 68 72 65 73  d exceeds iThres
b2e0: 68 6f 6c 64 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61  hold.  Only.** a
b2f0: 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
b300: 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
b310: 65 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ed at a time.  E
b320: 61 63 68 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  ach call.** to [
b330: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
b340: 6c 61 72 6d 28 29 5d 20 6f 76 65 72 77 72 69 74  larm()] overwrit
b350: 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  es the previous 
b360: 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
b370: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 64 69 73   callback is dis
b380: 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
b390: 20 78 43 61 6c 6c 62 61 63 6b 20 74 6f 20 61 20   xCallback to a 
b3a0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
b3b0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 70 61 72 61  .** .** The para
b3c0: 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61  meters to the ca
b3d0: 6c 6c 62 61 63 6b 20 61 72 65 20 74 68 65 20 70  llback are the p
b3e0: 41 72 67 20 76 61 6c 75 65 2c 20 74 68 65 20 0a  Arg value, the .
b3f0: 2a 2a 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ** amount of mem
b400: 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  ory currently in
b410: 20 75 73 65 2c 20 61 6e 64 20 74 68 65 20 73 69   use, and the si
b420: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ze of the.** all
b430: 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 70 72 6f  ocation that pro
b440: 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
b450: 63 6b 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ck.  The callbac
b460: 6b 20 77 69 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d  k will.** presum
b470: 61 62 6c 79 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ably invoke [sql
b480: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
b490: 66 72 65 65 20 75 70 20 6d 65 6d 6f 72 79 20 73  free up memory s
b4a0: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  pace..** The cal
b4b0: 6c 62 61 63 6b 20 6d 61 79 20 69 6e 76 6f 6b 65  lback may invoke
b4c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b4d0: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
b4e0: 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75  realloc()].** bu
b4f0: 74 20 69 66 20 69 74 20 64 6f 65 73 2c 20 6e 6f  t if it does, no
b500: 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   additional call
b510: 62 61 63 6b 73 20 77 69 6c 6c 20 62 65 20 69 6e  backs will be in
b520: 76 6f 6b 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  voked by.** the 
b530: 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c 73 2e  recursive calls.
b540: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
b550: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
b560: 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
b570: 20 77 6f 72 6b 73 20 62 79 20 72 65 67 69 73 74   works by regist
b580: 65 72 69 6e 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ering.** a memor
b590: 79 20 61 6c 61 72 6d 20 61 74 20 74 68 65 20 73  y alarm at the s
b5a0: 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
b5b0: 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20  nd invoking .** 
b5c0: 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
b5d0: 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 20 74 68  _memory()] in th
b5e0: 65 20 61 6c 61 72 6d 20 63 61 6c 6c 62 61 63 6b  e alarm callback
b5f0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  .  Application.*
b600: 2a 20 70 72 6f 67 72 61 6d 73 20 73 68 6f 75 6c  * programs shoul
b610: 64 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  d not attempt to
b620: 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
b630: 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29  3_memory_alarm()
b640: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
b650: 65 63 61 75 73 65 20 64 6f 69 6e 67 20 73 6f 20  ecause doing so 
b660: 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65 20 77  will interfere w
b670: 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
b680: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
b690: 6d 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e 0a 2a  mit()] module..*
b6a0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  /.int sqlite3_me
b6b0: 6d 6f 72 79 5f 61 6c 61 72 6d 28 0a 20 20 76 6f  mory_alarm(.  vo
b6c0: 69 64 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 76  id(*xCallback)(v
b6d0: 6f 69 64 20 2a 70 41 72 67 2c 20 73 71 6c 69 74  oid *pArg, sqlit
b6e0: 65 33 5f 75 69 6e 74 36 34 20 75 73 65 64 2c 20  e3_uint64 used, 
b6f0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 4e 29 2c  unsigned int N),
b700: 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
b710: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
b720: 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a  iThreshold.);...
b730: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b740: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
b750: 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
b760: 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  acks.***.** This
b770: 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
b780: 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
b790: 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 68  callback with th
b7a0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
b7b0: 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .  .** The autho
b7c0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
b7d0: 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
b7e0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
b7f0: 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
b800: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
b810: 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
b820: 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
b830: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
b840: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
b850: 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
b860: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
b870: 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
b880: 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
b890: 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
b8a0: 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
b8b0: 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
b8c0: 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
b8d0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
b8e0: 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
b8f0: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
b900: 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
b910: 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
b920: 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
b930: 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
b940: 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
b950: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49  d.** return SQLI
b960: 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74  TE_OK to allow t
b970: 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
b980: 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
b990: 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
b9a0: 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
b9b0: 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
b9c0: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
b9d0: 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
b9e0: 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
b9f0: 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
ba00: 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
ba10: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
ba20: 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
ba30: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a  th an error.  .*
ba40: 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 6f  *.** Depending o
ba50: 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 68  n the action, th
ba60: 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
ba70: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45  ] and [SQLITE_DE
ba80: 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 6f  NY] return.** co
ba90: 64 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 73  des might mean s
baa0: 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 65  omething differe
bab0: 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 74  nt or they might
bac0: 20 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a 2a   mean the same.*
bad0: 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 65  * thing.  If the
bae0: 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 20   action is, for 
baf0: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 66  example, to perf
bb00: 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 65  orm a delete ope
bb10: 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b  rtion,.** then [
bb20: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61  SQLITE_IGNORE] a
bb30: 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  nd [SQLITE_DENY]
bb40: 20 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 20   both cause the 
bb50: 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
bb60: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c  ation.** to fail
bb70: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
bb80: 20 42 75 74 20 69 66 20 74 68 65 20 61 63 74 69   But if the acti
bb90: 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 20  on is to read a 
bba0: 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 0a  specific column.
bbb0: 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 66  ** from a specif
bbc0: 69 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 5b  ic table, then [
bbd0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 6c  SQLITE_DENY] wil
bbe0: 6c 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  l cause the enti
bbf0: 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  re.** statement 
bc00: 74 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 4c  to fail but [SQL
bc10: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c 6c  ITE_IGNORE] will
bc20: 20 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 61   cause a NULL va
bc30: 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 61  lue to be.** rea
bc40: 64 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  d instead of the
bc50: 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 76   actual column v
bc60: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
bc70: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
bc80: 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
bc90: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
bca0: 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74  copy of.** the t
bcb0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
bcc0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
bcd0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
bce0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65  nterface..** The
bcf0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
bd00: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
bd10: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
bd20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  .** [SQLITE_COPY
bd30: 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
bd40: 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
bd50: 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
bd60: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75  tion.** to be au
bd70: 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 61  thorized.  The a
bd80: 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20  vailable action 
bd90: 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51  codes are.** [SQ
bda0: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75  LITE_COPY | docu
bdb0: 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c  mented separatel
bdc0: 79 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 74  y].  The third t
bdd0: 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20  hrough sixth.** 
bde0: 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
bdf0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 73  e callback are s
be00: 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
be10: 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
be20: 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
be30: 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
be40: 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
be50: 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
be60: 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72   is used when pr
be70: 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74  eparing SQL stat
be80: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
be90: 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72  ntrusted.** sour
bea0: 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
beb0: 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
bec0: 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79  ments do not try
bed0: 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a   to access data.
bee0: 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65  ** that they are
bef0: 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
bf00: 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
bf10: 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a  y do not try to.
bf20: 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  ** execute malic
bf30: 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
bf40: 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
bf50: 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
bf60: 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
bf70: 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
bf80: 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
bf90: 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
bfa0: 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
bfb0: 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
bfc0: 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
bfd0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
bfe0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
bff0: 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
c000: 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
c010: 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
c020: 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
c030: 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
c040: 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
c050: 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
c060: 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
c070: 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
c080: 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61  ing prepared tha
c090: 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  t disallows ever
c0a0: 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74  ything.** except
c0b0: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
c0c0: 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  ts.  .**.** Only
c0d0: 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
c0e0: 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
c0f0: 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
c100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
c110: 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
c120: 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
c130: 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
c140: 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
c150: 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
c160: 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69    A NULL authori
c170: 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
c180: 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
c190: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ** callback is i
c1a0: 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 66  nvoked.  The def
c1b0: 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
c1c0: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e  is NULL..**.** N
c1d0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
c1e0: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
c1f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
c200: 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c   during .** [sql
c210: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
c220: 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
c230: 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
c240: 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
c250: 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
c260: 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
c270: 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
c280: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
c290: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
c2a0: 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
c2b0: 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
c2c0: 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
c2d0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
c2e0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
c2f0: 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
c300: 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
c310: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c320: 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
c330: 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
c340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
c350: 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
c360: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
c370: 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
c380: 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
c390: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
c3a0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
c3b0: 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
c3c0: 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
c3d0: 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
c3e0: 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
c3f0: 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
c400: 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
c410: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
c420: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
c430: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
c440: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
c450: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
c460: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c470: 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
c480: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
c490: 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
c4a0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
c4b0: 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
c4c0: 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
c4d0: 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
c4e0: 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
c4f0: 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
c500: 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
c510: 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
c520: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
c530: 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
c540: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
c550: 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
c560: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
c570: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
c580: 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
c590: 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
c5a0: 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
c5b0: 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
c5c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
c5d0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
c5e0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
c5f0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
c600: 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
c610: 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
c620: 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
c630: 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
c640: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
c650: 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
c660: 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
c670: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
c680: 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
c690: 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
c6a0: 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
c6b0: 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
c6c0: 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
c6d0: 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
c6e0: 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
c6f0: 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
c700: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  .** function wil
c710: 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
c720: 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
c730: 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
c740: 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
c750: 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
c760: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
c770: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
c780: 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
c790: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
c7a0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
c7b0: 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
c7c0: 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
c7d0: 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
c7e0: 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
c7f0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
c800: 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
c810: 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
c820: 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
c830: 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
c840: 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
c850: 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
c860: 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
c870: 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
c880: 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
c890: 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
c8a0: 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  m .** top-level 
c8b0: 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
c8c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
c8d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
c8e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
c8f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
c900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
c910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
c920: 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
c930: 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
c940: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
c950: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
c960: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
c970: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
c980: 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
c990: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
c9a0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
c9b0: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
c9c0: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
c9d0: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
c9e0: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
c9f0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
ca00: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
ca10: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
ca20: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
ca30: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
ca40: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
ca50: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
ca60: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
ca70: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
ca80: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
ca90: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
caa0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
cab0: 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
cac0: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
cad0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
cae0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
caf0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
cb00: 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
cb10: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
cb20: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
cb30: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
cb40: 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
cb50: 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
cb60: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
cb70: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
cb80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cb90: 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
cba0: 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
cbb0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
cbc0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
cbd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cbe0: 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
cbf0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
cc00: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
cc10: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
cc20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cc30: 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
cc40: 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
cc50: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
cc60: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
cc70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc80: 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
cc90: 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
cca0: 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
ccb0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
ccc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
ccd0: 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
cce0: 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
ccf0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
cd00: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
cd10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
cd20: 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
cd30: 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
cd40: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
cd50: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
cd60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
cd70: 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
cd80: 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
cd90: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
cda0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
cdb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
cdc0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
cdd0: 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
cde0: 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
cdf0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
ce00: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
ce10: 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
ce20: 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
ce30: 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
ce40: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
ce50: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
ce60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
ce70: 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
ce80: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
ce90: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
cea0: 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
ceb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
cec0: 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
ced0: 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
cee0: 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
cef0: 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
cf10: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
cf20: 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
cf30: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
cf40: 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
cf50: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
cf60: 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
cf70: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
cf80: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
cf90: 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
cfa0: 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
cfb0: 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
cfc0: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
cfd0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
cfe0: 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
cff0: 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
d000: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
d010: 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
d020: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d030: 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
d040: 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
d050: 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
d060: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d080: 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
d090: 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
d0a0: 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
d0b0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d0c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d0d0: 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
d0e0: 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
d0f0: 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
d100: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
d110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d120: 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
d130: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
d140: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
d150: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
d160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d170: 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
d180: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
d190: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
d1a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d1b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d1c0: 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
d1d0: 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
d1e0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
d1f0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
d200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
d210: 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
d220: 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
d230: 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
d240: 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
d250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
d260: 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
d270: 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69    31   /* Functi
d280: 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  on Name   NULL  
d290: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
d2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d2c0: 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
d2d0: 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
d2e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
d2f0: 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
d300: 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
d310: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
d320: 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
d330: 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
d340: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
d350: 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
d360: 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
d370: 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
d380: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54  statements..** T
d390: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
d3a0: 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
d3b0: 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
d3c0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
d3d0: 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b 73   at the first [s
d3e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
d3f0: 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  or the evaluatio
d400: 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  n of an SQL stat
d410: 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61  ement..** The ca
d420: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
d430: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
d440: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
d450: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
d460: 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
d470: 65 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e 64  ent finishes and
d480: 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e 66   includes.** inf
d490: 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 20  ormation on how 
d4a0: 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
d4b0: 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ent ran..**.** T
d4c0: 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
d4d0: 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
d4e0: 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
d4f0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
d500: 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
d510: 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f  to change..*/.vo
d520: 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
d530: 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
d540: 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
d550: 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
d560: 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
d570: 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
d580: 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
d590: 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
d5a0: 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
d5b0: 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
d5c0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
d5d0: 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
d5e0: 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
d5f0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
d600: 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
d610: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
d620: 2d 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  - the progress c
d630: 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a  allback - that.*
d640: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  * is invoked per
d650: 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
d660: 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
d670: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
d680: 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  exec()],.** [sql
d690: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
d6a0: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
d6b0: 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
d6c0: 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
d6d0: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69   .** interface i
d6e0: 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
d6f0: 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
d700: 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
d710: 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
d720: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
d730: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
d740: 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61  ery N virtual ma
d750: 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a  chine opcodes,.*
d760: 2a 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  * where N is the
d770: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
d780: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
d790: 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  n. The progress 
d7a0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65  callback.** itse
d7b0: 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
d7c0: 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61 72   by the third ar
d7d0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66  gument to this f
d7e0: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75  unction. The fou
d7f0: 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rth.** argument 
d800: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
d810: 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74   is a void point
d820: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
d830: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
d840: 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65  ck.** function e
d850: 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
d860: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nvoked..**.** If
d870: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
d880: 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
d890: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f  lite3_step()], o
d8a0: 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  r [sqlite3_get_t
d8b0: 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c  able()].** resul
d8c0: 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e  ts in fewer than
d8d0: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67   N opcodes being
d8e0: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
d8f0: 74 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a  the progress .**
d900: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76   callback is nev
d910: 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a  er invoked..** .
d920: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
d930: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
d940: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
d950: 62 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f  be registered fo
d960: 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64  r each.** open d
d970: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d980: 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20  on.  Every call 
d990: 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
d9a0: 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
d9b0: 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
d9c0: 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70  results of the p
d9d0: 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a  revious call..**
d9e0: 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70   To remove the p
d9f0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
da00: 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73   altogether, pas
da10: 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68  s NULL as the th
da20: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
da30: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
da40: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
da50: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
da60: 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
da70: 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20  t other than 0, 
da80: 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74  then the current
da90: 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d   .** query is im
daa0: 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e  mediately termin
dab0: 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74  ated and any dat
dac0: 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f  abase changes ro
dad0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68  lled back..** Th
dae0: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71  e containing [sq
daf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
db00: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
db10: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
db20: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c  get_table()] cal
db30: 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  l returns SQLITE
db40: 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68  _INTERRUPT.   Th
db50: 69 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61  is feature.** ca
db60: 6e 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  n be used, for e
db70: 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65  xample, to imple
db80: 6d 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c  ment the "Cancel
db90: 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a  " button on a.**
dba0: 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
dbb0: 20 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a   box in a GUI..*
dbc0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
dbd0: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
dbe0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
dbf0: 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
dc00: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
dc10: 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
dc20: 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
dc30: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f  nnection.**.** O
dc40: 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64  pen the sqlite d
dc50: 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 66 69  atabase file "fi
dc60: 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66  lename".  The "f
dc70: 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d  ilename" is UTF-
dc80: 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72  8.** encoded for
dc90: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
dca0: 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  and UTF-16 encod
dcb0: 65 64 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ed in the native
dcc0: 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 66   byte order.** f
dcd0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
dce0: 36 28 29 2e 20 20 41 6e 20 5b 73 71 6c 69 74 65  6().  An [sqlite
dcf0: 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65  3*] handle is re
dd00: 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
dd10: 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65   even.** if an e
dd20: 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20  rror occurs. If 
dd30: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
dd40: 6f 70 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74  opened (or creat
dd50: 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
dd60: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54  ,.** then [SQLIT
dd70: 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
dd80: 64 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  d. Otherwise an 
dd90: 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
dda0: 74 75 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 5b  turned. The.** [
ddb0: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
ddc0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
ddd0: 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69  rmsg16()]  routi
dde0: 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
ddf0: 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
de00: 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
de10: 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
de20: 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
de30: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
de40: 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65   file does not e
de50: 78 69 73 74 2c 20 74 68 65 6e 20 61 20 6e 65 77  xist, then a new
de60: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
de70: 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 61 73 20  e created.** as 
de80: 6e 65 65 64 65 64 2e 20 20 54 68 65 20 64 65 66  needed.  The def
de90: 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
dea0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
deb0: 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
dec0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
ded0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 20  ) is called and 
dee0: 55 54 46 2d 31 36 20 69 66 20 73 71 6c 69 74 65  UTF-16 if sqlite
def0: 33 5f 6f 70 65 6e 31 36 20 69 73 20 75 73 65 64  3_open16 is used
df00: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
df10: 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
df20: 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
df30: 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
df40: 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ces associated.*
df50: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
df60: 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f  te3*] handle sho
df70: 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
df80: 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
df90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  .** [sqlite3_clo
dfa0: 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
dfb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
dfc0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
dfd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
dfe0: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
dff0: 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
e000: 65 6e 28 29 20 65 78 63 65 70 74 20 74 68 61 74  en() except that
e010: 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 74 77 6f  .** provides two
e020: 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
e030: 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
e040: 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76  ional control ov
e050: 65 72 20 74 68 65 0a 2a 2a 20 6e 65 77 20 64 61  er the.** new da
e060: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e070: 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
e080: 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 6f  rameter can be o
e090: 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  ne of:.**.** <ol
e0a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
e0b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
e0c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e0d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
e0e0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  E].** <li>  [SQL
e0f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
e100: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
e110: 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f  EN_CREATE].** </
e120: 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ol>.**.** The fi
e130: 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20  rst value opens 
e140: 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61  the database rea
e150: 64 2d 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65 20  d-only.  If the 
e160: 64 61 74 61 62 61 73 65 20 64 6f 65 73 0a 2a 2a  database does.**
e170: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
e180: 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
e190: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
e1a0: 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20  e second option 
e1b0: 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  opens.** the dat
e1c0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
e1d0: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 62 75  g and writing bu
e1e0: 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  t the database m
e1f0: 75 73 74 20 61 6c 72 65 61 64 79 0a 2a 2a 20 65  ust already.** e
e200: 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72  xist or an error
e210: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
e220: 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 20  he third option 
e230: 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
e240: 73 65 0a 2a 2a 20 66 6f 72 20 72 65 61 64 69 6e  se.** for readin
e250: 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e  g and writing an
e260: 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20  d creates it if 
e270: 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
e280: 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68  ady exist..** Th
e290: 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20  e third options 
e2a0: 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  is behavior that
e2b0: 20 69 73 20 75 73 65 64 20 61 6c 77 61 79 73 20   is used always 
e2c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
e2d0: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
e2e0: 33 5f 6f 70 65 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  3_open16()..**.*
e2f0: 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
e300: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
e310: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
e320: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
e330: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
e340: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
e350: 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
e360: 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
e370: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
e380: 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
e390: 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
e3a0: 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
e3b0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
e3c0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
e3d0: 72 20 74 68 65 6e 20 61 20 64 65 66 61 75 6c 74  r then a default
e3e0: 20 73 75 69 74 61 62 6c 65 20 66 6f 72 0a 2a 2a   suitable for.**
e3f0: 20 74 68 65 20 68 6f 73 74 20 65 6e 76 69 72 6f   the host enviro
e400: 6e 6d 65 6e 74 20 69 73 20 73 75 62 73 74 69 74  nment is substit
e410: 75 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  uted..**.** Note
e420: 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72   to windows user
e430: 73 3a 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  s:  The encoding
e440: 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
e450: 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
e460: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
e470: 65 6e 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  en() must be UTF
e480: 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
e490: 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
e4a0: 72 65 6e 74 6c 79 0a 2a 2a 20 64 65 66 69 6e 65  rently.** define
e4b0: 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
e4c0: 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
e4d0: 74 69 6f 6e 61 6c 20 63 68 61 72 61 63 74 65 72  tional character
e4e0: 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
e4f0: 74 65 64 0a 2a 2a 20 74 6f 20 55 54 46 2d 38 20  ted.** to UTF-8 
e500: 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
e510: 20 74 68 65 6d 20 69 6e 74 6f 20 73 71 6c 69 74   them into sqlit
e520: 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2f 0a 69 6e  e3_open()..*/.in
e530: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
e540: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
e550: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
e560: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
e570: 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
e580: 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
e590: 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
e5a0: 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
e5b0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
e5c0: 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
e5d0: 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
e5e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
e5f0: 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
e600: 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
e610: 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
e620: 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
e630: 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
e640: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
e650: 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
e660: 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
e670: 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
e680: 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
e690: 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
e6a0: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
e6b0: 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
e6c0: 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
e6d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
e6e0: 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
e6f0: 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
e700: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
e710: 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
e720: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
e730: 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
e740: 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
e750: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e760: 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
e770: 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
e780: 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  numeric.** [SQLI
e790: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
e7a0: 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ode] or [SQLITE_
e7b0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
e7c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
e7d0: 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f  e].** for the mo
e7e0: 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
e7f0: 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
e800: 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
e810: 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d  * with [sqlite3]
e820: 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 20 49   handle 'db'.  I
e830: 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
e840: 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74 68  ll failed but th
e850: 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
e860: 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
e870: 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
e880: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
e890: 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  e3_errcode().** 
e8a0: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a  is undefined. .*
e8b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e8c0: 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
e8d0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
e8e0: 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
e8f0: 6c 61 6e 67 61 75 67 65 0a 2a 2a 20 74 65 78 74  langauge.** text
e900: 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
e910: 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
e920: 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46  ther UTF8 or UTF
e930: 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
e940: 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
e950: 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
e960: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
e970: 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
e980: 79 2e 20 20 54 68 65 20 0a 2a 2a 20 73 74 72 69  y.  The .** stri
e990: 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72  ng may be overwr
e9a0: 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
e9b0: 61 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65  ated by subseque
e9c0: 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69  nt calls to SQLi
e9d0: 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  te.** interface 
e9e0: 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
e9f0: 20 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73   Calls to many s
ea00: 71 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f  qlite3_* functio
ea10: 6e 73 20 73 65 74 20 74 68 65 20 65 72 72 6f 72  ns set the error
ea20: 20 63 6f 64 65 20 61 6e 64 20 73 74 72 69 6e 67   code and string
ea30: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
ea40: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
ea50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
ea60: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
ea70: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
ea80: 5d 0a 2a 2a 20 28 6f 76 65 72 77 72 69 74 69 6e  ].** (overwritin
ea90: 67 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 76  g the previous v
eaa0: 61 6c 75 65 73 29 2e 20 4e 6f 74 65 20 74 68 61  alues). Note tha
eab0: 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
eac0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  te3_errcode()],.
ead0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
eae0: 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  sg()], and [sqli
eaf0: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
eb00: 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
eb10: 74 20 61 66 66 65 63 74 20 74 68 65 0a 2a 2a 20  t affect the.** 
eb20: 72 65 73 75 6c 74 73 20 6f 66 20 66 75 74 75 72  results of futur
eb30: 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20  e invocations.  
eb40: 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
eb50: 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
eb60: 74 20 72 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65  t return.** an e
eb70: 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70  rror code (examp
eb80: 6c 65 73 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  les: [sqlite3_da
eb90: 74 61 5f 63 6f 75 6e 74 28 29 5d 20 6f 72 20 5b  ta_count()] or [
eba0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
ebb0: 29 5d 29 20 64 6f 0a 2a 2a 20 6e 6f 74 20 63 68  )]) do.** not ch
ebc0: 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
ebd0: 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ode returned by 
ebe0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
ebf0: 0a 2a 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20  .** Assuming no 
ec00: 6f 74 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e  other intervenin
ec10: 67 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  g sqlite3_* API 
ec20: 63 61 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20  calls are made, 
ec30: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
ec40: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
ec50: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
ec60: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
ec70: 68 65 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73  he same error as
ec80: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20  .** the strings 
ec90: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
eca0: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
ecb0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
ecc0: 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
ecd0: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
ece0: 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
ecf0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
ed00: 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
ed10: 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
ed20: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
ed30: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ed40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
ed50: 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
ed60: 74 0a 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65  t.**.** Instance
ed70: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
ed80: 72 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65  represent single
ed90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
eda0: 20 20 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72    This.** is var
edb0: 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
edc0: 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
edd0: 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20  ement" or a .** 
ede0: 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
edf0: 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
ee00: 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
ee10: 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  nt"..** .** The 
ee20: 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
ee30: 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
ee40: 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
ee50: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
ee60: 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
ee70: 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
ee80: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
ee90: 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
eea0: 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
eeb0: 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
eec0: 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
eed0: 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69  t parameters usi
eee0: 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
eef0: 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
ef00: 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69  sqlite3_bind_* i
ef10: 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c  nterfaces]..** <
ef20: 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
ef30: 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
ef40: 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
ef50: 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
ef60: 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
ef70: 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
ef80: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
ef90: 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
efa0: 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
efb0: 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
efc0: 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
efd0: 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
efe0: 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
eff0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
f000: 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
f010: 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
f020: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
f030: 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
f040: 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
f050: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
f060: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
f070: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
f080: 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
f090: 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
f0a0: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
f0b0: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
f0c0: 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
f0d0: 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
f0e0: 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
f0f0: 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
f100: 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
f110: 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
f120: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
f130: 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  s. .**.** The fi
f140: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62  rst argument "db
f150: 22 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  " is an [sqlite3
f160: 20 7c 20 53 51 4c 69 74 65 20 64 61 74 61 62 61   | SQLite databa
f170: 73 65 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f  se handle] .** o
f180: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
f190: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
f1a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
f1b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
f1c0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ()]..** The seco
f1d0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71  nd argument "zSq
f1e0: 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  l" is the statem
f1f0: 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
f200: 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
f210: 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
f220: 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
f230: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
f240: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
f250: 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
f260: 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54 46  erfaces uses UTF
f270: 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  -8 and sqlite3_p
f280: 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
f290: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
f2a0: 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
f2b0: 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  -16..**.** If th
f2c0: 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
f2d0: 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e   is less.** than
f2e0: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
f2f0: 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
f300: 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
f310: 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a 2a  rminator.  If.**
f320: 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
f330: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
f340: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
f350: 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
f360: 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
f370: 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
f380: 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
f390: 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
f3a0: 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
f3b0: 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
f3c0: 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 20  0' character or 
f3d0: 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42  .** until the nB
f3e0: 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
f3f0: 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
f400: 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69  st..**.** *pzTai
f410: 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
f420: 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
f430: 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
f440: 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a 2a  d of the first.*
f450: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
f460: 69 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 72  in zSql.  This r
f470: 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d 70  outine only comp
f480: 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 20 73  iles the first s
f490: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 7a  tatement.** in z
f4a0: 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
f4b0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
f4c0: 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73   to what remains
f4d0: 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
f4e0: 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  ** *ppStmt is le
f4f0: 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
f500: 20 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73   compiled .** [s
f510: 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51  qlite3_stmt | SQ
f520: 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75  L statement stru
f530: 63 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20  cture] that can 
f540: 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
f550: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
f560: 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68  ep()].  Or if th
f570: 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
f580: 20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a   *ppStmt may be.
f590: 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20  ** set to NULL. 
f5a0: 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
f5b0: 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f 20  xt contained no 
f5c0: 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
f5d0: 74 20 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 74  t is and.** empt
f5e0: 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  y string or a co
f5f0: 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
f600: 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
f610: 4c 4c 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  LL.  The calling
f620: 0a 2a 2a 20 70 72 6f 63 65 64 75 72 65 20 69 73  .** procedure is
f630: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
f640: 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
f650: 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
f660: 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ment.** using [s
f670: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
f680: 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
f690: 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
f6a0: 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
f6b0: 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
f6c0: 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
f6d0: 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b  herwise an .** [
f6e0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
f6f0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
f700: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
f710: 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
f720: 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
f730: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
f740: 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
f750: 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
f760: 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
f770: 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
f780: 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
f790: 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
f7a0: 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
f7b0: 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
f7c0: 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
f7d0: 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20  couraged..** In 
f7e0: 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
f7f0: 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
f800: 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
f810: 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
f820: 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
f830: 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
f840: 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
f850: 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  he .** original 
f860: 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
f870: 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
f880: 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
f890: 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
f8a0: 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20  e a differently 
f8b0: 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a  in two ways:.**.
f8c0: 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
f8d0: 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
f8e0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
f8f0: 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
f900: 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
f910: 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
f920: 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
f930: 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
f940: 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
f950: 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
f960: 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
f970: 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
f980: 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
f990: 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68   If the schema h
f9a0: 61 73 20 63 68 61 6e 67 65 64 20 69 6e 20 61 20  as changed in a 
f9b0: 77 61 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b 65  way.** that make
f9c0: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
f9d0: 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
f9e0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
f9f0: 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
fa00: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
fa10: 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c  CHEMA].  But unl
fa20: 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ike the legacy b
fa30: 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45  ehavior, [SQLITE
fa40: 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e  _SCHEMA] is.** n
fa50: 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  ow a fatal error
fa60: 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  .  Calling [sqli
fa70: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
fa80: 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
fa90: 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
faa0: 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74  or go away.  Not
fab0: 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  e: use [sqlite3_
fac0: 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e  errmsg()] to fin
fad0: 64 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68  d the text of th
fae0: 65 20 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 72  e parsing.** err
faf0: 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  or that results 
fb00: 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43  in an [SQLITE_SC
fb10: 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a  HEMA] return..**
fb20: 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
fb30: 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72  >.** When an err
fb40: 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b  or occurs, .** [
fb50: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
fb60: 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
fb70: 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 20  of the detailed 
fb80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
fb90: 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  R | result codes
fba0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
fbb0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
fbc0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
fbd0: 65 73 5d 20 73 75 63 68 20 61 73 20 64 69 72 65  es] such as dire
fbe0: 63 74 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 67  ctly..** The leg
fbf0: 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
fc00: 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73   that [sqlite3_s
fc10: 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
fc20: 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
fc30: 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ic.** [SQLITE_ER
fc40: 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
fc50: 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68   and you would h
fc60: 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
fc70: 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cond call to.** 
fc80: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
fc90: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
fca0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
fcb0: 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
fcc0: 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20  roblem..** With 
fcd0: 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
fce0: 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
fcf0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
fd00: 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
fd10: 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20   is.** returned 
fd20: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
fd30: 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
fd40: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
fd50: 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
fd60: 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
fd70: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
fd80: 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
fd90: 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
fda0: 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
fdb0: 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
fdc0: 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
fdd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
fde0: 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
fdf0: 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
fe00: 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
fe10: 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
fe20: 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
fe30: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
fe40: 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
fe50: 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
fe60: 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
fe70: 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
fe80: 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
fe90: 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
fea0: 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
feb0: 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
fec0: 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
fed0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
fee0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
fef0: 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
ff00: 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
ff10: 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
ff20: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
ff30: 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
ff40: 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
ff50: 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
ff60: 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
ff70: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
ff80: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
ff90: 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
ffa0: 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
ffb0: 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
ffc0: 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
ffd0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
ffe0: 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
fff0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
10000 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
10010 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
10020 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
10030 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
10040 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
10050 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
10060 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
10070 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
10080 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
10090 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
100a0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
100b0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
100c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
100d0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
100e0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
100f0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
10100 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
10110 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
10120 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
10130 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
10140 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
10150 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10160 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
10170 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
10180 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
10190 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
101a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
101b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
101c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
101d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
101e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
101f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
10200 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
10210 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
10220 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
10230 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
10240 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
10250 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
10260 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61   CAPI3REF:  Dyna
10270 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
10280 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  lue Object.**.**
10290 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
102a0 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20  amic typing for 
102b0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
102c0 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63 61  ores.  Values ca
102d0 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72  n .** be integer
102e0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
102f0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
10300 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
10310 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 73  L.  When.** pass
10320 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 65  ing around value
10330 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61  s internally, ea
10340 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70 72  ch value is repr
10350 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 6e  esented as.** an
10360 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10370 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
10380 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
10390 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
103a0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
103b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 51  ** CAPI3REF:  SQ
103c0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
103d0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
103e0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
103f0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
10400 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
10410 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
10420 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
10430 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
10440 74 65 72 20 74 6f 20 73 75 63 68 20 61 6e 20 6f  ter to such an o
10450 62 6a 65 63 74 20 69 73 20 74 68 65 0a 2a 2a 20  bject is the.** 
10460 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
10470 74 6f 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20  to user-defined 
10480 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  SQL functions..*
10490 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
104a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
104b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
104c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
104d0 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  F:  Binding Valu
104e0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
104f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a 20  tatements.**.** 
10500 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
10510 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
10520 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
10530 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
10540 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  nts,.** one or m
10550 6f 72 65 20 6c 69 74 65 72 61 6c 73 20 63 61 6e  ore literals can
10560 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20 61   be replace by a
10570 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
10580 65 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 6f  e of these.** fo
10590 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rms:.**.** <ul>.
105a0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
105b0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
105c0 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20    :AAA.** <li>  
105d0 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @AAA.** <li>  $V
105e0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
105f0 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * In the paramet
10600 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61  er forms shown a
10610 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  bove NNN is an i
10620 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
10630 2a 2a 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70  ** AAA is an alp
10640 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
10650 66 69 65 72 20 61 6e 64 20 56 56 56 20 69 73 20  fier and VVV is 
10660 61 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20  a variable name 
10670 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20  according.** to 
10680 74 68 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73  the syntax rules
10690 20 6f 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67   of the TCL prog
106a0 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65  ramming language
106b0 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20  ..** The values 
106c0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
106d0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
106e0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
106f0 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e 20   names").** can 
10700 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
10710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
10720 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
10730 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
10740 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10750 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
10760 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
10770 65 73 20 61 6c 77 61 79 73 20 69 73 20 61 20 70  es always is a p
10780 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
10790 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
107a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
107b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
107c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
107d0 2a 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  * its variants. 
107e0 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   The second.** a
107f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
10800 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 61  ndex of the para
10810 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
10820 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
10830 6d 65 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e 20  meter has.** an 
10840 69 6e 64 65 78 20 6f 66 20 31 2e 20 57 68 65 6e  index of 1. When
10850 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 20   the same named 
10860 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
10870 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
10880 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 20  , second.** and 
10890 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
108a0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
108b0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
108c0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
108d0 72 65 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 65  rence.  The inde
108e0 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 70  x for.** named p
108f0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
10900 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
10910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
10920 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
10930 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64  name()] API if d
10940 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
10950 65 78 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a 2a  ex for "?NNN".**
10960 20 70 61 72 61 6d 65 74 65 73 20 69 73 20 74 68   parametes is th
10970 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
10980 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
10990 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
109a0 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69   1 and the compi
109b0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d  le-time.** param
109c0 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f  eter SQLITE_MAX_
109d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
109e0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
109f0 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 20  999)..** See <a 
10a00 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 6d  href="limits.htm
10a10 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c 2f  l">limits.html</
10a20 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  a> for additiona
10a30 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
10a40 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
10a50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
10a60 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
10a70 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
10a80 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a  *.** In those.**
10a90 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
10aa0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
10ab0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
10ac0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
10ad0 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68  f bytes.** in th
10ae0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
10af0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
10b00 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
10b10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
10b20 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e 6f  he.** string, no
10b30 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
10b40 63 68 61 72 61 63 74 65 72 73 2e 20 20 54 68 65  characters.  The
10b50 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
10b60 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  tes does not inc
10b70 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65  lude the zero-te
10b80 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
10b90 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a  end of strings..
10ba0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
10bb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
10bc0 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
10bd0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
10be0 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66   is.** number of
10bf0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
10c00 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
10c10 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
10c20 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
10c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
10c40 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
10c50 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
10c60 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
10c70 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
10c80 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
10c90 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
10ca0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 78  e BLOB or.** tex
10cb0 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  t after SQLite h
10cc0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
10cd0 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69 66   it.  If the fif
10ce0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  th argument is t
10cf0 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 61  he.** special va
10d00 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
10d10 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 69  IC], then the li
10d20 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74 68  brary assumes th
10d30 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69  at the informati
10d40 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 74  on.** is in stat
10d50 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
10d60 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
10d70 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
10d80 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 69  d.  If the.** fi
10d90 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
10da0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
10db0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
10dc0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
10dd0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 76   its.** own priv
10de0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
10df0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
10e00 2c 20 62 65 66 6f 72 65 20 74 68 65 20 73 71 6c  , before the sql
10e10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
10e20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10e30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10e40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
10e50 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
10e60 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
10e70 74 68 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th n that.** is 
10e80 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
10e90 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
10ea0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
10eb0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
10ec0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
10ed0 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65   to hold it size
10ee0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
10ef0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
10f00 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
10f10 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
10f20 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65  e as place-holde
10f30 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
10f40 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
10f50 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
10f60 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
10f70 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
10f80 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f  crement BLOB I/O
10f90 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ] routines..**.*
10fa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
10fb0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
10fc0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
10fd0 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
10fe0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
10ff0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
11000 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
11010 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
11020 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
11030 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e  ep()]..** Bindin
11040 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
11050 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
11060 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
11070 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20  ine..** Unbound 
11080 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
11090 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
110a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  LL..**.** These 
110b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
110c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
110d0 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72  uccess or an err
110e0 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e  or code if.** an
110f0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
11100 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47  g.  [SQLITE_RANG
11110 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
11120 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
11130 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
11140 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49  of range.  [SQLI
11150 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
11160 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20  urned if malloc 
11170 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54  fails..** [SQLIT
11180 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74  E_MISUSE] is ret
11190 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
111a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
111b0 65 64 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 0a  ed on a virtual.
111c0 2a 2a 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  ** machine that 
111d0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
111e0 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
111f0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
11200 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  alized..*/.int s
11210 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
11220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
11230 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
11240 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
11250 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
11260 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
11270 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
11280 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
11290 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
112a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
112b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
112c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
112d0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
112e0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
112f0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
11300 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
11310 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11320 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
11330 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
11340 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
11350 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
11360 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
11370 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
11380 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
11390 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
113a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
113b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
113c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
113d0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
113e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
113f0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
11400 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
11410 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
11420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
11430 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
11440 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
11450 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65  r Of Host Parame
11460 74 65 72 73 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  ters.**.** Retur
11470 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 68 6f  n the largest ho
11480 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  st parameter ind
11490 65 78 20 69 6e 20 74 68 65 20 70 72 65 63 6f 6d  ex in the precom
114a0 70 69 6c 65 64 20 73 74 61 74 65 6d 65 6e 74 20  piled statement 
114b0 67 69 76 65 6e 0a 2a 2a 20 61 73 20 74 68 65 20  given.** as the 
114c0 61 72 67 75 6d 65 6e 74 2e 20 20 57 68 65 6e 20  argument.  When 
114d0 74 68 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74  the host paramet
114e0 65 72 73 20 61 72 65 20 6f 66 20 74 68 65 20 66  ers are of the f
114f0 6f 72 6d 73 20 6c 69 6b 65 20 22 3a 41 41 41 22  orms like ":AAA"
11500 0a 2a 2a 20 6f 72 20 22 3f 22 2c 20 74 68 65 6e  .** or "?", then
11510 20 74 68 65 79 20 61 72 65 20 61 73 73 69 67 6e   they are assign
11520 65 64 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e  ed sequential in
11530 63 72 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73  creasing numbers
11540 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69   beginning.** wi
11550 74 68 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76  th one, so the v
11560 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
11570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
11580 61 72 61 6d 65 74 65 72 73 2e 20 20 48 6f 77 65  arameters.  Howe
11590 76 65 72 0a 2a 2a 20 69 66 20 74 68 65 20 73 61  ver.** if the sa
115a0 6d 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  me host paramete
115b0 72 20 6e 61 6d 65 20 69 73 20 75 73 65 64 20 6d  r name is used m
115c0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 2c 20 65  ultiple times, e
115d0 61 63 68 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a  ach occurrance.*
115e0 2a 20 69 73 20 67 69 76 65 6e 20 74 68 65 20 73  * is given the s
115f0 61 6d 65 20 6e 75 6d 62 65 72 2c 20 73 6f 20 74  ame number, so t
11600 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11610 64 20 69 6e 20 74 68 61 74 20 63 61 73 65 20 69  d in that case i
11620 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  s the number.** 
11630 6f 66 20 75 6e 69 71 75 65 20 68 6f 73 74 20 70  of unique host p
11640 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 2e 20  arameter names. 
11650 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65 74   If host paramet
11660 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
11670 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 72 65 20 75 73  "?NNN".** are us
11680 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69 73  ed (where NNN is
11690 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68 65   an integer) the
116a0 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62 65  n there might be
116b0 20 67 61 70 73 20 69 6e 20 74 68 65 0a 2a 2a 20   gaps in the.** 
116c0 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74 68  numbering and th
116d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
116e0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
116f0 63 65 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  ce is the index 
11700 6f 66 20 74 68 65 0a 2a 2a 20 68 6f 73 74 20 70  of the.** host p
11710 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74 68  arameter with th
11720 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
11730 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  value..*/.int sq
11740 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
11750 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
11760 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
11770 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
11780 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
11790 65 74 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eter.**.** This 
117a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
117b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
117c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
117d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  h parameter in a
117e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
117f0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
11800 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73  atement]..** Hos
11810 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  t parameters of 
11820 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20  the form ":AAA" 
11830 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
11840 56 56 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a  VV" have a name.
11850 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ** which is the 
11860 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72  string ":AAA" or
11870 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
11880 22 2e 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ".  .** In other
11890 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
118a0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
118b0 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "@".** is incl
118c0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
118d0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
118e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
118f0 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e  orm "?" or "?NNN
11900 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a  " have no name..
11910 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
11920 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
11930 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
11940 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
11950 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
11960 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
11970 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
11980 72 61 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c  rameter is namel
11990 65 73 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c  ess,.** then NUL
119a0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
119b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
119c0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ing is always in
119d0 20 74 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e   the.** UTF-8 en
119e0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
119f0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
11a00 65 72 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c  er was originall
11a10 79 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61  y specified.** a
11a20 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
11a30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
11a40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
11a50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
11a60 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
11a70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
11a80 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
11a90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
11aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11ab0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
11ac0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
11ad0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69  n Name.**.** Thi
11ae0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
11af0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  s the index of a
11b00 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
11b10 77 69 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e  with the given n
11b20 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ame..** The name
11b30 20 6d 75 73 74 20 6d 61 74 63 68 20 65 78 61 63   must match exac
11b40 74 6c 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61  tly.  If no para
11b50 6d 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67  meter with the g
11b60 69 76 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a  iven name is .**
11b70 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30   found, return 0
11b80 2e 20 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d  .  Parameter nam
11b90 65 73 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e  es must be UTF8.
11ba0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11bb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
11bc0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
11bd0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
11be0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
11bf0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
11c00 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
11c10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
11c20 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  ent.**.** Contra
11c30 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
11c40 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
11c50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
11c60 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
11c70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
11c80 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
11c90 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71  gs] on a .** [sq
11ca0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
11cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11cc0 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  .  Use this rout
11cd0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20  ine to.** reset 
11ce0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
11cf0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
11d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
11d10 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
11d20 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
11d30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
11d40 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
11d50 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
11d60 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
11d70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
11d80 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
11d90 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
11da0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
11db0 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20  stmt | compiled 
11dc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  SQL statement]. 
11dd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
11de0 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74  urns 0.** if pSt
11df0 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61  mt is an SQL sta
11e00 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
11e10 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
11e20 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c   (for .** exampl
11e30 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f  e an UPDATE)..*/
11e40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
11e50 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
11e60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
11e70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11e80 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
11e90 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
11ea0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11eb0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
11ec0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
11ed0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
11ee0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
11ef0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
11f00 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
11f10 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
11f20 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
11f30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
11f40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
11f50 46 38 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71  F8 string and sq
11f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
11f70 65 31 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  e16().** returns
11f80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
11f90 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
11fa0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
11fb0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71  er is the.** [sq
11fc0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
11fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11fe0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
11ff0 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
12000 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65  ement..** The se
12010 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
12020 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d  s the column num
12030 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ber.  The left-m
12040 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a  ost column is.**
12050 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
12060 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
12070 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
12080 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
12090 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  er the .** [sqli
120a0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
120b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
120c0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
120d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
120e0 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  ()].** or until 
120f0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71  the next call sq
12100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
12110 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
12120 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
12130 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  * on the same co
12140 6c 75 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lumn..*/.const c
12150 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
12160 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
12170 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
12180 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
12190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
121a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
121b0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
121c0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
121d0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
121e0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
121f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12200 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
12210 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
12220 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
12230 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
12240 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
12250 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54  sult of a SELECT
12260 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
12270 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
12280 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
12290 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
122a0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
122b0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
122c0 65 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46  er a UTF8 or UTF
122d0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
122e0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
122f0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
12300 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
12310 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
12320 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
12330 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
12340 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
12350 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12360 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
12370 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
12380 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
12390 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73   until.** the [s
123a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
123b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
123c0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
123d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
123e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
123f0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
12400 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
12410 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
12420 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
12430 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
12440 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
12450 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
12460 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
12470 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
12480 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
12490 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
124a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
124b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
124c0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
124d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
124e0 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
124f0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  L statement]..**
12500 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
12510 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
12520 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
12530 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
12540 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
12550 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
12560 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
12570 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
12580 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
12590 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
125a0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
125b0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
125c0 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
125d0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
125e0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
125f0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
12600 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
12610 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77  urn NULL. Otherw
12620 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
12630 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66   the .** name of
12640 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
12650 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e  tabase, table an
12660 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
12670 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ery result.** co
12680 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
12690 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
126a0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
126b0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
126c0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
126d0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 20 55  th "16" return U
126e0 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64  TF-16.** encoded
126f0 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
12700 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
12710 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
12720 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
12730 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
12740 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
12750 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
12760 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
12770 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
12780 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
12790 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
127a0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
127b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
127c0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
127d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
127e0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
127f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
12800 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
12810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
12820 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
12830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
12840 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
12850 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
12860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
12870 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
12880 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
12890 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
128a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
128b0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
128c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
128d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
128e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
128f0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
12900 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
12910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12920 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
12930 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
12940 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  esult.**.** The 
12950 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12960 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  is a [sqlite3_st
12970 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
12980 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a  L statement]. .*
12990 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
129a0 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20  ent is a SELECT 
129b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
129c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
129d0 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  the .** returned
129e0 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66 20   result set  of 
129f0 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
12a00 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
12a10 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
12a20 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
12a30 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
12a40 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
12a50 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
12a60 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74  s returned. If t
12a70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
12a80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
12a90 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
12aa0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
12ab0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
12ac0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
12ad0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
12ae0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
12af0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
12b00 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  . For example, i
12b10 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
12b20 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
12b30 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
12b40 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
12b50 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** And the follo
12b60 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  wing statement c
12b70 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
12b80 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
12b90 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
12ba0 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  Then this routin
12bb0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
12bc0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
12bd0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
12be0 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c  nd.** result col
12bf0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
12c00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
12c10 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
12c20 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69  ult column.** (i
12c30 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
12c40 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
12c50 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
12c60 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
12c70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
12c80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
12c90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
12ca0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
12cb0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
12cc0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
12cd0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
12ce0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
12cf0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
12d00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
12d10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
12d20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
12d30 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
12d40 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
12d50 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
12d60 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
12d70 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
12d80 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
12d90 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
12da0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
12db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
12dc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
12dd0 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e  t *, int i);.con
12de0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
12df0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
12e00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
12e10 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43  ,int);../* .** C
12e20 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61  API3REF:  Evalua
12e30 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
12e40 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
12e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  an [sqlite3_stmt
12e60 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   | SQL statement
12e70 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
12e80 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a  red with a call.
12e90 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71  ** to either [sq
12ea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
12eb0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12ec0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
12ed0 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20  or to one of.** 
12ee0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
12ef0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
12f00 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
12f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
12f20 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  )],.** then this
12f30 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
12f40 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
12f50 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
12f60 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73  aluate the .** s
12f70 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
12f80 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
12f90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
12fa0 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70  his sqlite3_step
12fb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
12fc0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
12fd0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
12fe0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
12ff0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
13000 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
13010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
13020 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
13030 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
13040 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
13050 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
13060 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
13070 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
13080 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
13090 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
130a0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
130b0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
130c0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
130d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
130e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
130f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
13100 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
13110 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
13120 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74 65   the lagacy inte
13130 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
13140 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
13150 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
13160 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  USY], .** [SQLIT
13170 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
13180 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
13190 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
131a0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69  E_MISUSE]..** Wi
131b0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
131c0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
131d0 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f  e other [SQLITE_
131e0 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
131f0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
13200 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
13210 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
13220 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  e] might be retu
13230 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e  rned as.** well.
13240 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  .**.** [SQLITE_B
13250 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
13260 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
13270 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
13280 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
13290 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
132a0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
132b0 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20  ts job.  If the 
132c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43  statement is a C
132d0 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75  OMMIT.** or occu
132e0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
132f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
13300 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
13310 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
13320 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
13330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
13340 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e   not a COMMIT an
13350 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
13360 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
13370 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
13380 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
13390 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
133a0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
133b0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b  tinuing..**.** [
133c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
133d0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
133e0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
133f0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
13400 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
13410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
13420 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
13430 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
13440 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
13450 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
13460 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
13470 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
13480 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
13490 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
134a0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
134b0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  state..**.** If 
134c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
134d0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
134e0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
134f0 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c  a, then .** [SQL
13500 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75  ITE_ROW] is retu
13510 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
13520 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
13530 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72   is ready.** for
13540 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
13550 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  he caller. The v
13560 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
13570 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  essed using.** t
13580 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
13590 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20  mn_int | column 
135a0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
135b0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
135c0 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
135d0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
135e0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
135f0 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53   data..** .** [S
13600 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
13610 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
13620 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
13630 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
13640 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
13650 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
13660 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
13670 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
13680 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
13690 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
136a0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
136b0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
136c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
136d0 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67  .** With the leg
136e0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
136f0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
13700 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70  rror code (examp
13710 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le:.** [SQLITE_I
13720 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
13730 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
13740 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
13750 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
13760 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
13770 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
13780 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
13790 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
137a0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
137b0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74  tatement].  In t
137c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
137d0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
137e0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
137f0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
13800 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
13810 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
13820 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
13830 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
13840 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
13850 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
13860 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
13870 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
13880 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f  d on a [sqlite3_
13890 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
138a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
138b0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
138c0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
138d0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
138e0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
138f0 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f  t had .** previo
13900 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
13910 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
13920 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
13930 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
13940 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
13950 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
13960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
13970 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
13980 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
13990 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
139a0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
139b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
139c0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
139d0 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  </b>.** In the l
139e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
139f0 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33   .** the sqlite3
13a00 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61  _step() API alwa
13a10 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
13a20 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
13a30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13a40 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
13a50 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  y error other th
13a60 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
13a70 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
13a80 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
13a90 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  st call [sqlite3
13aa0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
13ab0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
13ac0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
13ad0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
13ae0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51   specific.** [SQ
13af0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
13b00 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ult codes] that 
13b10 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
13b20 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
13b30 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
13b40 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
13b50 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
13b60 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
13b70 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
13b80 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
13b90 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
13ba0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
13bb0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
13bc0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
13bd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
13be0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
13bf0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
13c00 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
13c10 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
13c20 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
13c30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
13c40 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20  ], then the .** 
13c50 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 53  more specific [S
13c60 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
13c70 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
13c80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
13c90 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
13ca0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
13cb0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
13cc0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
13cd0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
13ce0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
13cf0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
13d00 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a  * CAPI3REF:.**.*
13d10 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
13d20 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e  ber of values in
13d30 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
13d40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
13d50 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  et..**.** After 
13d60 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
13d70 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20  e3_step()] that 
13d80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
13d90 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69  ROW], this routi
13da0 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ne.** will retur
13db0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
13dc0 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33   as the [sqlite3
13dd0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
13de0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66   function..** Af
13df0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
13e00 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
13e10 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d an [SQLITE_DON
13e20 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  E], [SQLITE_BUSY
13e30 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49  ], or.** a [SQLI
13e40 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72  TE_ERROR | error
13e50 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72   code], or befor
13e60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
13e70 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20  )] has been .** 
13e80 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73  called on the [s
13e90 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
13ea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13eb0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
13ec0 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f  time,.** this ro
13ed0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
13ee0 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ro..*/.int sqlit
13ef0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
13f00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
13f10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
13f20 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
13f30 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a   Datatypes.**.**
13f40 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20   Every value in 
13f50 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
13f60 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
13f70 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
13f80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
13f90 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
13fa0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
13fb0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
13fc0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
13fd0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
13fe0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
13ff0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
14000 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  l>.**.** These c
14010 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
14020 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
14030 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
14040 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
14050 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
14060 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
14070 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
14080 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
14090 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
140a0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
140b0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
140c0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
140d0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
140e0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
140f0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
14100 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
14110 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
14120 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
14130 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
14140 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
14150 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
14160 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
14170 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
14180 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
14190 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
141a0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
141b0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
141c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
141d0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
141e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
141f0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
14200 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
14210 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  ts Values From A
14220 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65   Query.**.** The
14230 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
14240 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
14250 62 6f 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61  bout the informa
14260 74 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e  tion.** in a sin
14270 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
14280 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74  e current result
14290 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
142a0 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61    In every.** ca
142b0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
142c0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
142d0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  er to the .** [s
142e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51  qlite3_stmt | SQ
142f0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  L statement] tha
14300 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76  t is being.** ev
14310 61 6c 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c  aluate (the [sql
14320 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74  ite3_stmt*] that
14330 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
14340 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
14350 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
14360 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
14370 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65  ants) and.** the
14380 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14390 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
143a0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
143b0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
143c0 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  n .** should be 
143d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
143e0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
143f0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
14400 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
14410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
14420 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
14430 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
14440 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
14450 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  * the column ind
14460 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
14470 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
14480 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
14490 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
144a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
144b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tine returns .**
144c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
144d0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
144e0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
144f0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
14500 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
14510 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
14520 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
14530 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
14540 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
14550 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
14560 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
14570 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
14580 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
14590 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
145a0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
145b0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
145c0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
145d0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
145e0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
145f0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
14600 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
14610 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
14620 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
14630 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
14640 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
14650 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
14660 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
14670 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
14680 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
14690 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
146a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
146b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
146c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
146d0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
146e0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
146f0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
14700 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
14710 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72  mn_bytes() .** r
14720 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
14730 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
14740 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
14750 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
14760 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
14770 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
14780 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
14790 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
147a0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
147b0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
147c0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
147d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
147e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
147f0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
14800 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
14810 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
14820 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
14830 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
14840 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
14850 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
14860 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
14870 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
14880 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
14890 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
148a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
148b0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
148c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
148d0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
148e0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
148f0 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
14900 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
14910 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
14920 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
14930 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
14940 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
14950 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
14960 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
14970 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
14980 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
14990 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
149a0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
149b0 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
149c0 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73  lt in UTF-16 ins
149d0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20  tead of UTF-8.  
149e0 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
149f0 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
14a00 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
14a10 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
14a20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
14a30 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
14a40 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
14a50 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
14a60 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
14a70 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
14a80 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
14a90 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
14aa0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
14ab0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
14ac0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
14ad0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
14ae0 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72  to do the conver
14af0 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  sion.** automati
14b00 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
14b10 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
14b20 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
14b30 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ons that.** are 
14b40 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
14b50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
14b60 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
14b70 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
14b80 74 65 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75  ternal <th> Requ
14b90 65 73 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c  ested <th> .** <
14ba0 74 72 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20  tr><th>  Type   
14bb0 20 3c 74 68 3e 20 20 20 20 54 79 70 65 20 20 20   <th>    Type   
14bc0 3c 74 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  <th> Conversion.
14bd0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
14be0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
14bf0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
14c00 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
14c10 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
14c20 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
14c30 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
14c40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
14c50 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
14c60 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
14c70 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
14c80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
14c90 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
14ca0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
14cb0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
14cc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
14cd0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
14ce0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
14cf0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
14d00 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
14d10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
14d20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
14d30 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
14d40 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
14d50 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
14d60 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
14d70 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66    <td> Same as f
14d80 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  or INTEGER->TEXT
14d90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
14da0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
14db0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
14dc0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
14dd0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
14de0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
14df0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
14e00 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
14e10 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
14e20 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
14e30 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
14e40 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
14e50 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
14e60 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
14e70 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
14e80 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
14e90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
14ea0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
14eb0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
14ec0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
14ed0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
14ee0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
14ef0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
14f00 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
14f10 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
14f20 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
14f30 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
14f40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
14f50 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
14f60 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
14f70 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
14f80 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
14f90 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
14fa0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
14fb0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
14fc0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
14fd0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
14fe0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14ff0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
15000 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
15010 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
15020 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
15030 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
15040 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
15050 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
15060 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
15070 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
15080 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c  ts.** on equaval
15090 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
150a0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
150b0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
150c0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
150d0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
150e0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
150f0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
15100 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
15110 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
15120 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
15130 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
15140 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
15150 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
15160 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
15170 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
15180 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
15190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
151a0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
151b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
151c0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
151d0 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70  lidated. .** Typ
151e0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
151f0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
15200 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
15210 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
15220 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
15230 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
15240 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
15250 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
15260 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
15270 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a  column_text() .*
15280 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71  *          or sq
15290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
152a0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
152b0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
152c0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
152d0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
152e0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
152f0 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a  ring.</p></li>.*
15300 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  *.** <li><p>  Th
15310 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
15320 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
15330 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
15340 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
15350 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69  **          sqli
15360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
15370 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
15380 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
15390 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
153a0 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
153b0 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  -16.</p></li>.**
153c0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
153d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
153e0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
153f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
15400 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
15410 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
15420 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
15430 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
15440 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
15450 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
15460 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
15470 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  /p></li>.** </ul
15480 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
15490 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
154a0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
154b0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
154c0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
154d0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
154e0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
154f0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
15500 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
15510 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
15520 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
15530 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
15540 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
15550 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
15560 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
15570 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
15580 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
15590 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
155a0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69  , but sometime i
155b0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
155c0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
155d0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
155e0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
155f0 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  idated.  .**.** 
15600 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
15610 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
15620 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
15630 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
15640 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
15650 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
15660 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75   ways:.**.**  <u
15670 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
15680 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
15690 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
156a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
156b0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
156c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
156d0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
156e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
156f0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
15700 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
15710 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
15720 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
15730 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
15740 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75  6()</li>.**  </u
15750 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
15760 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
15770 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
15780 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
15790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
157a0 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c  lob(),.** or sql
157b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
157c0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
157d0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69  rce the result i
157e0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a  nto the desired.
157f0 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ** format, then 
15800 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
15810 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
15820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15830 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20  bytes16() to.** 
15840 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
15850 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
15860 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f   not mix call to
15870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15880 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  text() or.** sql
15890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
158a0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
158b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
158c0 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20  bytes16().  And 
158d0 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61  do not.** mix ca
158e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
158f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77  olumn_text16() w
15900 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
15910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
15920 73 28 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  s()..*/.const vo
15930 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
15940 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
15950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
15960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
15970 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
15980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
15990 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
159a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
159b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
159c0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
159d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
159e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
159f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
15a00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
15a10 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
15a20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
15a30 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
15a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
15a50 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
15a60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
15a70 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
15a80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
15a90 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
15aa0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
15ab0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
15ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
15ad0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
15ae0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
15af0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
15b00 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
15b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
15b20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
15b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
15b40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
15b50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
15b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
15b70 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
15b80 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
15b90 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
15ba0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
15bb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
15bc0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a  ed to delete a .
15bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
15be0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
15bf0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74  statement]. If t
15c00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
15c10 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75 63  .** executed suc
15c20 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f  cessfully, or no
15c30 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
15c40 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f  l, then SQLITE_O
15c50 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  K is returned..*
15c60 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  * If execution o
15c70 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
15c80 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a  failed then an .
15c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
15ca0 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f   | error code] o
15cb0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
15cc0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
15cd0 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
15ce0 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a  s returned. .**.
15cf0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
15d00 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
15d10 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
15d20 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
15d30 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
15d40 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61  e3_stmt | virtua
15d50 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20  l machine].  If 
15d60 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
15d70 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  ine has not .** 
15d80 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
15d90 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
15da0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
15db0 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
15dc0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
15dd0 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74   error or an int
15de0 65 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73  errupt.  (See [s
15df0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15e00 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70  ()].) .** Incomp
15e10 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
15e20 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
15e30 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
15e40 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a   cancelled,  .**
15e50 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
15e60 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
15e70 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51   and the .** [SQ
15e80 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73  LITE_ERROR | res
15e90 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ult code] return
15ea0 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
15eb0 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
15ec0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
15ed0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
15ee0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
15ef0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
15f00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
15f10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
15f20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
15f30 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
15f40 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
15f50 74 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t a .** [sqlite3
15f60 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
15f70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
15f80 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20  object..** back 
15f90 74 6f 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20  to it's initial 
15fa0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
15fb0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
15fc0 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
15fd0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
15fe0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
15ff0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
16000 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
16010 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
16020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
16030 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
16040 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
16050 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
16060 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
16070 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
16080 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
16090 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
160a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
160b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
160c0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
160d0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
160e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
160f0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
16100 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
16110 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
16120 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
16130 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
16140 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
16150 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
16160 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
16170 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
16180 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
16190 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
161a0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
161b0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
161c0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
161d0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
161e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
161f0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
16200 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
16210 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
16220 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
16230 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
16240 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
16250 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
16260 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
16270 5b 73 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62  [sqlite3 | datab
16280 61 73 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74  ase handle] that
16290 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51   holds the.** SQ
162a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
162b0 67 72 65 67 61 74 65 20 69 73 20 74 6f 20 62 65  gregate is to be
162c0 20 61 64 64 65 64 20 6f 72 20 72 65 64 65 66 69   added or redefi
162d0 6e 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65  ned. If a single
162e0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
162f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
16300 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69  atabase handle i
16310 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
16320 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  SQL.** functions
16330 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6d   or aggregates m
16340 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
16350 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
16360 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61  h database.** ha
16370 6e 64 6c 65 20 77 69 74 68 20 77 68 69 63 68 20  ndle with which 
16380 74 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65  they will be use
16390 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
163a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
163b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
163c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
163d0 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
163e0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
163f0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
16400 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
16410 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
16420 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
16430 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
16440 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
16450 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
16460 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
16470 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
16480 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
16490 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
164a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
164b0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
164c0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
164d0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
164e0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
164f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16500 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16510 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
16520 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
16530 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
16540 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
16550 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
16560 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
16570 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
16580 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
16590 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
165a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
165b0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
165c0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
165d0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
165e0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
165f0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
16600 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
16610 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
16620 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
16630 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
16640 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
16650 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
16660 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
16670 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
16680 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
16690 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
166a0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
166b0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
166c0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
166d0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
166e0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
166f0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
16700 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
16710 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
16720 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
16730 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
16740 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
16750 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
16760 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
16770 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
16780 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
16790 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
167a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
167b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
167c0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
167d0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
167e0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
167f0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
16800 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
16810 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
16820 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
16830 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
16840 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16850 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
16860 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
16870 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
16880 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
16890 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
168a0 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
168b0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
168c0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
168d0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
168e0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
168f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
16900 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
16910 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
16920 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
16930 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
16940 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
16950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
16960 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
16970 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
16980 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
16990 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
169a0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
169b0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
169c0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
169d0 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
169e0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
169f0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
16a00 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
16a10 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
16a20 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
16a30 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
16a40 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
16a50 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
16a60 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
16a70 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
16a80 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
16a90 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
16aa0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
16ab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
16ac0 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
16ad0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
16ae0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
16af0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
16b00 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
16b10 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
16b20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
16b30 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
16b40 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
16b50 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
16b60 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
16b70 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
16b80 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
16b90 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
16ba0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
16bb0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
16bc0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
16bd0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
16be0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
16bf0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
16c00 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
16c10 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
16c20 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
16c30 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
16c40 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
16c50 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
16c60 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
16c70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
16c80 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71   used..*/.int sq
16c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
16ca0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
16cb0 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   *,.  const char
16cc0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
16cd0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
16ce0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
16cf0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78  oid*,.  void (*x
16d00 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
16d10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
16d20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
16d30 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
16d40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
16d50 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
16d60 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
16d70 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
16d80 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
16d90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
16da0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
16db0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e3*,.  const voi
16dc0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
16dd0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
16de0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
16df0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a  void*,.  void (*
16e00 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
16e10 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
16e20 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
16e30 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
16e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
16e50 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
16e60 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
16e70 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
16e80 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
16e90 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
16ea0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
16eb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
16ec0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
16ed0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
16ee0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
16ef0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
16f00 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
16f10 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
16f20 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
16f30 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
16f40 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
16f50 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
16f60 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
16f70 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
16f80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
16f90 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
16fa0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
16fb0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
16fc0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
16fd0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
16fe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
16ff0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
17000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
17010 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
17020 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
17030 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
17040 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
17050 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
17060 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
17070 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
17080 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
17090 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
170a0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
170b0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
170c0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
170d0 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
170e0 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
170f0 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
17100 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
17110 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
17120 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
17130 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
17140 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
17150 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
17160 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
17170 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
17180 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
17190 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
171a0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
171b0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
171c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
171d0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
171e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
171f0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
17200 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
17210 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
17220 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
17230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
17240 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
17250 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
17260 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 0a  recover(void);..
17270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17280 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
17290 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
172a0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
172b0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
172c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
172d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
172e0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
172f0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
17300 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
17310 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
17320 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
17330 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
17340 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
17350 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
17360 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
17370 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
17380 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
17390 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
173a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
173b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
173c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
173d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
173e0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
173f0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
17400 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
17410 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
17420 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
17430 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
17440 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
17450 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
17460 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
17470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
17480 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
17490 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
174a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
174b0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
174c0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
174d0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
174e0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
174f0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
17500 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
17510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
17520 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
17530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
17540 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
17550 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
17560 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
17570 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
17580 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
17590 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
175a0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
175b0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
175c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
175d0 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  ] pointer instea
175e0 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  d.** of an [sqli
175f0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
17600 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
17610 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
17620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17630 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
17640 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
17650 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
17660 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
17670 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
17680 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
17690 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
176a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
176b0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
176c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
176d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
176e0 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
176f0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
17700 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
17710 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
17720 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
17730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
17740 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
17750 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
17760 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
17770 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
17780 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
17790 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
177a0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
177b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
177c0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
177d0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
177e0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
177f0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
17800 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
17810 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
17820 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65  rmation (in orde
17830 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
17840 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69 67 69  e value is origi
17850 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74 68 61  nal a string tha
17860 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
17870 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69  umber).** then i
17880 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65  t is done.  Othe
17890 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
178a0 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ion occurs.  The
178b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54   .** [SQLITE_INT
178c0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
178d0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
178e0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
178f0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
17900 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
17910 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
17920 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
17930 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74  r that.** is ret
17940 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
17950 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
17960 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
17970 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
17980 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
17990 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
179a0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
179b0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
179c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
179d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
179e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
179f0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
17a00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
17a10 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
17a20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
17a30 29 5d 2e 20 20 0a 2a 2f 0a 63 6f 6e 73 74 20 76  )].  .*/.const v
17a40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
17a50 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
17a60 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
17a70 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
17a80 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
17a90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
17aa0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
17ab0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
17ac0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
17ad0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
17ae0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
17af0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
17b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
17b10 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
17b30 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
17b40 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
17b50 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
17b60 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
17b70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
17b80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
17b90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
17ba0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
17bb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
17bc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
17bd0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
17be0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
17bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
17c00 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
17c10 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
17c20 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
17c30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
17c40 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
17c50 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
17c60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
17c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17c80 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
17c90 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
17ca0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  t.**.** The impl
17cb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
17cc0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
17cd0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
17ce0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
17cf0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
17d00 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
17d10 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20  eir state.  The 
17d20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
17d30 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61  routine.** is ca
17d40 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
17d50 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
17d60 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65   a new structure
17d70 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a   of size nBytes.
17d80 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c  ** is allocated,
17d90 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74   zeroed, and ret
17da0 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65  urned.  On subse
17db0 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72  quent calls (for
17dc0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67   the.** same agg
17dd0 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29  regate instance)
17de0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
17df0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
17e00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
17e10 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
17e20 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
17e30 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
17e40 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
17e50 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  data..**.** The 
17e60 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64  buffer allocated
17e70 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
17e80 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  tically by SQLit
17e90 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65  e whan the aggre
17ea0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
17eb0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
17ec0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
17ed0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
17ee0 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
17ef0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
17f00 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
17f10 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
17f20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
17f30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
17f40 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
17f50 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
17f60 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
17f70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 76 6f 69  function..*/.voi
17f80 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
17f90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
17fa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
17fb0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
17fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
17fd0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
17fe0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ions.**.** The p
17ff0 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
18000 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
18010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18020 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
18030 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
18040 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
18050 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 72  nes.** used to r
18060 65 67 69 73 74 65 72 20 75 73 65 72 20 66 75 6e  egister user fun
18070 63 74 69 6f 6e 73 20 69 73 20 61 76 61 69 6c 61  ctions is availa
18080 62 6c 65 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ble to.** the im
18090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
180a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 75 73 69  the function usi
180b0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a 2f  ng this call..*/
180c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
180d0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
180e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
180f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
18100 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
18110 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
18120 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
18130 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
18140 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
18150 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
18160 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d   associate meta-
18170 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
18180 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
18190 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
181a0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
181b0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
181c0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
181d0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
181e0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
181f0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
18200 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
18210 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
18220 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70  ta-data may be p
18230 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
18240 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
18250 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
18260 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
18270 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
18280 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
18290 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
182a0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
182b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
182c0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
182d0 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73  .** meta-data as
182e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
182f0 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
18300 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
18310 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
18320 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
18330 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
18340 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
18350 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
18360 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
18370 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
18380 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
18390 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
183a0 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
183b0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
183c0 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
183d0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
183e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
183f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
18400 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
18410 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
18420 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
18430 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
18440 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
18450 6e 74 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  nt value to the 
18460 63 75 72 72 65 6e 74 20 53 51 4c 20 66 75 6e 63  current SQL func
18470 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c 20 77 68  tion.** call, wh
18480 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
18490 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 49  ond parameter. I
184a0 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20 68  f no meta-data h
184b0 61 73 20 62 65 65 6e 20 73 65 74 20 66 6f 72 0a  as been set for.
184c0 2a 2a 20 74 68 61 74 20 76 61 6c 75 65 2c 20 74  ** that value, t
184d0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
184e0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
184f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18500 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
18510 69 73 20 75 73 65 64 20 74 6f 20 61 73 73 6f 63  is used to assoc
18520 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
18530 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a 20 66 75  ith an SQL.** fu
18540 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
18550 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
18560 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
18570 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61  r to the meta-da
18580 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61 73 73 6f  ta.** to be asso
18590 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
185a0 4e 74 68 20 75 73 65 72 20 66 75 6e 63 74 69 6f  Nth user functio
185b0 6e 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  n argument value
185c0 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20  . The fourth.** 
185d0 70 61 72 61 6d 65 74 65 72 20 73 70 65 63 69 66  parameter specif
185e0 69 65 73 20 61 20 64 65 73 74 72 75 63 74 6f 72  ies a destructor
185f0 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 63 61   that will be ca
18600 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d 65 74 61  lled on the meta
18610 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69 6e 74 65  -.** data pointe
18620 72 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 20  r to release it 
18630 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
18640 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 20 49  nger required. I
18650 66 20 74 68 65 20 0a 2a 2a 20 64 65 73 74 72 75  f the .** destru
18660 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c 20 69 74  ctor is NULL, it
18670 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 2e   is not invoked.
18680 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
18690 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73  ce, meta-data is
186a0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
186b0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
186c0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
186d0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
186e0 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
186f0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
18700 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
18710 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
18720 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2f 0a 76 6f  variables..*/.vo
18730 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
18740 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
18750 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
18760 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
18770 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
18780 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c 20  _context*, int, 
18790 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
187a0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
187b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
187c0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
187d0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
187e0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
187f0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
18800 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
18810 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
18820 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
18830 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
18840 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
18850 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
18860 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
18870 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
18880 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
18890 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
188a0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
188b0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
188c0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
188d0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
188e0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
188f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
18900 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
18910 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
18920 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
18930 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
18940 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
18950 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
18960 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
18970 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
18980 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
18990 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
189a0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
189b0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
189c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
189d0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
189e0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
189f0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
18a00 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
18a10 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
18a20 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
18a30 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
18a40 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
18a50 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
18a60 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
18a70 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
18a80 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
18a90 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
18aa0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
18ab0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
18ac0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
18ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
18ae0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
18af0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
18b00 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
18b10 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
18b20 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
18b30 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
18b40 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
18b50 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
18b60 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
18b70 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
18b80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18b90 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
18ba0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
18bb0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
18bc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
18bd0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
18be0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
18bf0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
18c00 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
18c10 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
18c20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61  lite3_bind_*] fa
18c30 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
18c40 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e  s used.** to bin
18c50 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
18c60 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
18c70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18c80 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
18c90 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
18ca0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
18cb0 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d  te3_bind_* docum
18cc0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a  entation] for.**
18cd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
18ce0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
18cf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
18d00 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
18d10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
18d20 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
18d30 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
18d40 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
18d50 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
18d60 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20 54  an exception.  T
18d70 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  he.** parameter 
18d80 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
18d90 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
18da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
18db0 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65 20  r16().** is the 
18dc0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
18dd0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
18de0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
18df0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75 73  lt_toobig() caus
18e00 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  e the function i
18e10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
18e20 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65 72   to throw and er
18e30 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
18e40 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
18e50 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a  BLOB is to long.
18e60 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ** to represent.
18e70 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
18e80 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
18e90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
18ea0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
18eb0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
18ec0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
18ed0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
18ee0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
18ef0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
18f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
18f10 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
18f20 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
18f30 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
18f40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
18f50 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
18f60 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
18f70 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
18f80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
18f90 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
18fa0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
18fb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
18fc0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
18fd0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
18fe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
18ff0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
19000 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
19010 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
19020 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
19030 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
19040 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
19050 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
19060 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
19070 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
19080 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
19090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
190a0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
190b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
190c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
190d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
190e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
190f0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
19100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
19110 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
19120 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
19130 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
19140 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
19150 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
19160 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
19170 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
19180 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
19190 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
191a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
191b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
191c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
191d0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
191e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
191f0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
19200 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
19210 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
19220 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
19230 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
19240 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
19250 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
19260 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
19270 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
19280 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
19290 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
192a0 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  t. .**.** The na
192b0 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
192c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
192d0 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
192e0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
192f0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
19300 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
19310 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
19320 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
19330 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
19340 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
19350 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
19360 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 20 49 6e  llation16().  In
19370 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
19380 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
19390 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
193a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
193b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
193c0 64 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  d argument must 
193d0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
193e0 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
193f0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
19400 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
19410 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
19420 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
19430 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
19440 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
19450 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
19460 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
19470 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
19480 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
19490 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
194a0 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  an or UTF-16 big
194b0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
194c0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  vely..**.** A po
194d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
194e0 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
194f0 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
19500 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
19510 2a 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  * argument. If i
19520 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
19530 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
19540 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
19550 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
19560 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
19570 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
19580 20 61 6e 79 6d 6f 72 65 29 2e 20 45 61 63 68 20   anymore). Each 
19590 74 69 6d 65 20 74 68 65 20 75 73 65 72 0a 2a 2a  time the user.**
195a0 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69   supplied functi
195b0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  on is invoked, i
195c0 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  t is passed a co
195d0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
195e0 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
195f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
19600 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
19610 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f  te_collation() o
19620 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
19630 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
19640 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  ) as its first p
19650 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19660 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
19670 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 75  guments to the u
19680 73 65 72 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ser-supplied rou
19690 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
196a0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
196b0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 5b  presented by a [
196c0 6c 65 6e 67 74 68 2c 20 64 61 74 61 5d 20 70 61  length, data] pa
196d0 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
196e0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
196f0 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
19700 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
19710 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
19720 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
19730 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
19740 74 65 72 65 64 2e 20 54 68 65 20 75 73 65 72 20  tered. The user 
19750 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
19760 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
19770 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
19780 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   if.** the first
19790 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
197a0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
197b0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
197c0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74  the second.** st
197d0 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
197e0 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
197f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19800 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
19810 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
19820 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
19830 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
19840 20 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20   excapt that it 
19850 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
19860 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
19870 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
19880 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
19890 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
198a0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
198b0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
198c0 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
198d0 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
198e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
198f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
19900 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
19910 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
19920 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
19930 32 28 29 2e 20 20 43 6f 6c 6c 61 74 69 6f 6e 73  2().  Collations
19940 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
19950 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  hen.** they are 
19960 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
19970 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
19980 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
19990 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ion functions.**
199a0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71   or when the [sq
199b0 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65  lite3*] database
199c0 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65   handle is close
199d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
199e0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
199f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
19a00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
19a10 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
19a20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
19a30 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
19a40 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
19a50 72 65 6c 65 61 73 65 73 2e 20 20 54 68 65 20 6f  releases.  The o
19a60 74 68 65 72 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  ther collation c
19a70 72 65 61 74 69 6f 6e 0a 2a 2a 20 66 75 6e 63 74  reation.** funct
19a80 69 6f 6e 73 20 61 72 65 20 73 74 61 62 6c 65 2e  ions are stable.
19a90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19aa0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
19ab0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
19ac0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
19ad0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
19ae0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
19af0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
19b00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
19b10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
19b20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
19b30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
19b40 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
19b50 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
19b60 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
19b70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
19b80 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
19b90 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
19ba0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
19bb0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
19bc0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
19bd0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
19be0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
19bf0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
19c00 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
19c10 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
19c20 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
19c30 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
19c40 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
19c50 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
19c60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
19c70 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
19c80 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
19c90 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
19ca0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
19cb0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
19cc0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
19cd0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
19ce0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
19cf0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
19d00 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
19d10 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
19d20 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
19d30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68  he.** database h
19d40 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c  andle to be call
19d50 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
19d60 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
19d70 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a  on sequence is.*
19d80 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  * required..**.*
19d90 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
19da0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
19db0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
19dc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
19dd0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
19de0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
19df0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
19e00 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
19e10 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
19e20 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
19e30 69 6e 20 55 54 46 2d 38 2e 20 49 66 20 73 71 6c  in UTF-8. If sql
19e40 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
19e50 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
19e60 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20  d, the names.** 
19e70 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
19e80 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
19e90 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
19ea0 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  r. A call to eit
19eb0 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  her.** function 
19ec0 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
19ed0 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
19ee0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
19ef0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
19f00 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
19f10 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
19f20 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
19f30 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19f40 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
19f50 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
19f60 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
19f70 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
19f80 28 29 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61  (). The second a
19f90 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
19fa0 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c  atabase.** handl
19fb0 65 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  e. The third arg
19fc0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
19fd0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
19fe0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
19ff0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
1a000 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
1a010 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
1a020 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
1a030 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
1a040 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
1a050 6e 20 72 65 71 75 69 72 65 64 2e 20 54 68 65 20  n required. The 
1a060 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1a070 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1a080 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
1a090 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
1a0a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
1a0b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a0c0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
1a0d0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
1a0e0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
1a0f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1a100 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
1a110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1a120 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
1a130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
1a140 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1a150 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1a160 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1a170 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
1a180 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
1a190 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
1a1a0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
1a1b0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
1a1c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
1a1d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
1a1e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
1a1f0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
1a200 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
1a210 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
1a220 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
1a230 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
1a240 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
1a250 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
1a260 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
1a270 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
1a280 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
1a290 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
1a2a0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
1a2b0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
1a2c0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
1a2d0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
1a2e0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
1a2f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1a300 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
1a310 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a320 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a330 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
1a340 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
1a350 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
1a360 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
1a370 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
1a380 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
1a390 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
1a3a0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
1a3b0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
1a3c0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
1a3d0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
1a3e0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
1a3f0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
1a400 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
1a410 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
1a420 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
1a430 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
1a440 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
1a450 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
1a460 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
1a470 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
1a480 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1a490 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
1a4a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1a4b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1a4c0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
1a4d0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
1a4e0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
1a4f0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
1a500 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
1a510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
1a520 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
1a530 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
1a540 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  e.**.** This fun
1a550 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
1a560 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
1a570 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
1a580 74 69 6f 6e 0a 2a 2a 20 61 20 6e 75 6d 62 65 72  tion.** a number
1a590 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
1a5a0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
1a5b0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
1a5c0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
1a5d0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
1a5e0 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
1a5f0 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20  p requests with 
1a600 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
1a610 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
1a620 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
1a630 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
1a640 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61  p to .** the nea
1a650 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
1a660 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
1a670 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a680 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65   actually .** re
1a690 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
1a6a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1a6b0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
1a6c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
1a6d0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
1a6e0 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
1a6f0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
1a700 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
1a710 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 49 66 20   Files.**.** If 
1a720 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
1a730 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
1a740 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
1a750 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
1a760 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
1a770 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
1a780 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
1a790 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
1a7a0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
1a7b0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
1a7c0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
1a7d0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
1a7e0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
1a7f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
1a800 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
1a810 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
1a820 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
1a830 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
1a840 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65  tory..**.** Once
1a850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1a860 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1a870 64 2c 20 63 68 61 6e 67 69 6e 67 20 74 68 69 73  d, changing this
1a880 20 76 61 72 69 61 62 6c 65 20 77 69 6c 6c 0a 2a   variable will.*
1a890 2a 20 69 6e 76 61 6c 69 64 61 74 65 20 74 68 65  * invalidate the
1a8a0 20 63 75 72 72 65 6e 74 20 74 65 6d 70 6f 72 61   current tempora
1a8b0 72 79 20 64 61 74 61 62 61 73 65 2c 20 69 66 20  ry database, if 
1a8c0 61 6e 79 2e 20 20 47 65 6e 65 72 61 6c 6c 79 20  any.  Generally 
1a8d0 73 70 65 61 6b 69 6e 67 2c 0a 2a 2a 20 69 74 20  speaking,.** it 
1a8e0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 69  is not safe to i
1a8f0 6e 76 6f 6b 65 20 74 68 69 73 20 72 6f 75 74 69  nvoke this routi
1a900 6e 65 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ne after [sqlite
1a910 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 0a 2a 2a  3_open()] has.**
1a920 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f   been called..*/
1a930 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
1a940 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
1a950 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
1a960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54  .** CAPI3REF:  T
1a970 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1a980 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e 20  e Databse Is In 
1a990 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
1a9a0 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73  .**.** Test to s
1a9b0 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ee whether or no
1a9c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  t the database c
1a9d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
1a9e0 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f  autocommit.** mo
1a9f0 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45  de.  Return TRUE
1aa00 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 41   if it is and FA
1aa10 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74  LSE if not.  Aut
1aa20 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
1aa30 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  on.** by default
1aa40 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73  .  Autocommit is
1aa50 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 42   disabled by a B
1aa60 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61  EGIN statement a
1aa70 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20  nd reenabled.** 
1aa80 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d  by the next COMM
1aa90 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a  IT or ROLLBACK..
1aaa0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1aab0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
1aac0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1aad0 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
1aae0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
1aaf0 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57  dle Associated W
1ab00 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53  ith A Prepared S
1ab10 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52  tatement.**.** R
1ab20 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74  eturn the [sqlit
1ab30 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
1ab40 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
1ab50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
1ab60 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
1ab70 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
1ab80 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73  ** This is the s
1ab90 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
1aba0 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
1abb0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1abc0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
1abd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1abe0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1abf0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
1ac00 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
1ac10 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1ac20 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
1ac30 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
1ac40 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
1ac50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a  te3_stmt*);.../*
1ac60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1ac70 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
1ac80 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
1ac90 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
1aca0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
1acb0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1acc0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ck functions to 
1acd0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1ace0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
1acf0 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65  n.** is committe
1ad00 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b  d or rolled back
1ad10 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75  .  The pArg argu
1ad20 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
1ad30 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
1ad40 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
1ad50 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
1ad60 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
1ad70 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
1ad80 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1ad90 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
1ada0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
1adb0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
1adc0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
1add0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
1ade0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
1adf0 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
1ae00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
1ae10 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
1ae20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1ae30 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
1ae40 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
1ae50 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
1ae60 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
1ae70 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
1ae80 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
1ae90 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
1aea0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
1aeb0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
1aec0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
1aed0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
1aee0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
1aef0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
1af00 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
1af10 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
1af20 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68  ack to occur. Th
1af30 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  e .** callback i
1af40 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
1af50 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
1af60 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
1af70 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62  rolled.** back b
1af80 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
1af90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1afa0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1afb0 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
1afc0 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
1afd0 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
1afe0 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
1aff0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1b000 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
1b010 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
1b020 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
1b030 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
1b040 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
1b050 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
1b060 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1b070 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
1b080 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
1b090 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1b0a0 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63  .** Register a c
1b0b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b0c0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
1b0d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
1b0e0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1b0f0 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
1b100 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
1b110 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
1b120 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
1b130 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
1b140 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
1b150 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
1b160 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1b170 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
1b180 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
1b190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1b1a0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
1b1b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1b1c0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1b1d0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
1b1e0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
1b1f0 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
1b200 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
1b210 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68  d or deleted. Th
1b220 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b230 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b240 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
1b250 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1b260 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
1b270 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68  pdate_hook(). Th
1b280 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
1b290 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
1b2a0 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f  s one of SQLITE_
1b2b0 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44  INSERT, SQLITE_D
1b2c0 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f  ELETE or SQLITE_
1b2d0 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e  UPDATE, dependin
1b2e0 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72  g.** on the oper
1b2f0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
1b300 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
1b310 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68  o be invoked. Th
1b320 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
1b330 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
1b340 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b350 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
1b360 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
1b370 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
1b380 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
1b390 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
1b3a0 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  . The final call
1b3b0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
1b3c0 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
1b3d0 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74  of the row. In t
1b3e0 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
1b3f0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
1b400 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
1b410 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
1b420 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
1b430 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
1b440 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
1b450 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
1b460 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
1b470 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
1b480 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
1b490 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
1b4a0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
1b4b0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
1b4c0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
1b4d0 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
1b4e0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
1b4f0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
1b500 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
1b510 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ned..*/.void *sq
1b520 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
1b530 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
1b540 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
1b550 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
1b560 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
1b570 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
1b580 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
1b590 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
1b5a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
1b5b0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
1b5c0 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
1b5d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
1b5e0 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
1b5f0 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
1b600 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
1b610 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
1b620 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
1b630 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
1b640 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1b650 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
1b660 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1b670 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
1b680 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
1b690 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
1b6a0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
1b6b0 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
1b6c0 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
1b6d0 73 61 62 6c 65 64 20 6f 6e 20 61 20 74 68 72 65  sabled on a thre
1b6e0 61 64 2d 62 79 2d 74 68 72 65 61 64 20 62 61 73  ad-by-thread bas
1b6f0 69 73 2e 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c  is..** Each call
1b700 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1b710 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
1b720 62 6c 65 73 20 63 61 63 68 65 20 73 68 61 72 69  bles cache shari
1b730 6e 67 20 6f 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63  ng only for.** c
1b740 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 72 65 61 74  onnections creat
1b750 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ed in the same t
1b760 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
1b770 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
1b780 61 6c 6c 65 64 2e 0a 2a 2a 20 54 68 65 72 65 20  alled..** There 
1b790 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
1b7a0 66 6f 72 20 73 68 61 72 69 6e 67 20 63 61 63 68  for sharing cach
1b7b0 65 20 62 65 74 77 65 65 6e 20 64 61 74 61 62 61  e between databa
1b7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
1b7d0 2a 20 72 75 6e 6e 69 6e 67 20 69 6e 20 64 69 66  * running in dif
1b7e0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 2e 0a  ferent threads..
1b7f0 2a 2a 0a 2a 2a 20 53 68 61 72 69 6e 67 20 6d 75  **.** Sharing mu
1b800 73 74 20 62 65 20 64 69 73 61 62 6c 65 64 20 70  st be disabled p
1b810 72 69 6f 72 20 74 6f 20 73 68 75 74 74 69 6e 67  rior to shutting
1b820 20 64 6f 77 6e 20 61 20 74 68 72 65 61 64 20 6f   down a thread o
1b830 72 20 65 6c 73 65 0a 2a 2a 20 74 68 65 20 74 68  r else.** the th
1b840 72 65 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20 6d  read will leak m
1b850 65 6d 6f 72 79 2e 20 20 43 61 6c 6c 20 74 68 69  emory.  Call thi
1b860 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1b870 6e 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a  n argument of.**
1b880 20 30 20 74 6f 20 74 75 72 6e 20 6f 66 66 20 73   0 to turn off s
1b890 68 61 72 69 6e 67 2e 20 20 4f 72 20 75 73 65 20  haring.  Or use 
1b8a0 74 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  the sqlite3_thre
1b8b0 61 64 5f 63 6c 65 61 6e 75 70 28 29 20 41 50 49  ad_cleanup() API
1b8c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1b8d0 74 69 6e 65 20 6d 75 73 74 20 6e 6f 74 20 62 65  tine must not be
1b8e0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 61 6e 79   called when any
1b8f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b900 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 63 74  tions.** are act
1b910 69 76 65 20 69 6e 20 74 68 65 20 63 75 72 72 65  ive in the curre
1b920 6e 74 20 74 68 72 65 61 64 2e 20 20 45 6e 61 62  nt thread.  Enab
1b930 6c 69 6e 67 20 6f 72 20 64 69 73 61 62 6c 69 6e  ling or disablin
1b940 67 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  g shared.** cach
1b950 65 20 77 68 69 6c 65 20 74 68 65 72 65 20 61 72  e while there ar
1b960 65 20 61 63 74 69 76 65 20 64 61 74 61 62 61 73  e active databas
1b970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69  e connections wi
1b980 6c 6c 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  ll result.** in 
1b990 6d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  memory corruptio
1b9a0 6e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  n..**.** When th
1b9b0 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69  e shared cache i
1b9c0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 0a 2a  s enabled, the.*
1b9d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74  * following rout
1b9e0 69 6e 65 73 20 6d 75 73 74 20 61 6c 77 61 79 73  ines must always
1b9f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
1ba00 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 3a  the same thread:
1ba10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
1ba20 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  n()], [sqlite3_p
1ba30 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1ba40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 0a  qlite3_step()],.
1ba50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
1ba60 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  t()], [sqlite3_f
1ba70 69 6e 61 6c 69 7a 65 28 29 5d 2c 20 61 6e 64 20  inalize()], and 
1ba80 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1ba90 5d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 75  ]..** This is du
1baa0 65 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  e to the fact th
1bab0 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61  at the shared ca
1bac0 63 68 65 20 6d 61 6b 65 73 20 75 73 65 20 6f 66  che makes use of
1bad0 0a 2a 2a 20 74 68 72 65 61 64 2d 73 70 65 63 69  .** thread-speci
1bae0 66 69 63 20 73 74 6f 72 61 67 65 20 73 6f 20 74  fic storage so t
1baf0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 61  hat it will be a
1bb00 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 73 68 61  vailable for sha
1bb10 72 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 74 68  ring.** with oth
1bb20 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a  er connections..
1bb30 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
1bb40 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
1bb50 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
1bb60 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73  d cache.  When s
1bb70 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1bb80 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73  s enabled, the s
1bb90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
1bba0 64 75 6c 65 28 29 20 41 50 49 20 75 73 65 64 20  dule() API used 
1bbb0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
1bbc0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
1bbd0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
1bbe0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
1bbf0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1bc00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1bc10 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
1bc20 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  e was.** enabled
1bc30 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
1bc40 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
1bc50 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65  SQLITE_ERROR | e
1bc60 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73  rror code].** is
1bc70 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
1bc80 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
1bc90 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
1bca0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
1bcb0 6f 72 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70  or backward comp
1bcc0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
1bcd0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
1bce0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
1bcf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1bd00 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f  REF:  Attempt To
1bd10 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
1bd20 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20  y.**.** Attempt 
1bd30 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 20  to free N bytes 
1bd40 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
1bd50 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
1bd60 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20  on-essential.** 
1bd70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bd80 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
1bd90 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 20  atabase library 
1bda0 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79  (example: memory
1bdb0 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63   .** used to cac
1bdc0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
1bdd0 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
1bde0 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  formance)..**.**
1bdf0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
1be00 73 20 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20  s not a part of 
1be10 73 74 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e  standard builds.
1be20 20 20 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65    It is only cre
1be30 61 74 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74  ated.** if SQLit
1be40 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
1be50 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e  th the SQLITE_EN
1be60 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
1be70 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f  GEMENT macro..*/
1be80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
1be90 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
1bea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1beb0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
1bec0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
1bed0 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73  **.** Place a "s
1bee0 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68  oft" limit on th
1bef0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
1bf00 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
1bf10 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
1bf20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69  .** SQLite withi
1bf30 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  n the current th
1bf40 72 65 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65  read. If an inte
1bf50 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
1bf60 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
1bf70 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
1bf80 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ed the specified
1bf90 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
1bfa0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1bfb0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  )] is invoked.**
1bfc0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1bfd0 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
1bfe0 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
1bff0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  the allocation i
1c000 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  s made..**.** Th
1c010 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
1c020 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73  d "soft", becaus
1c030 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65  e if [sqlite3_re
1c040 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
1c050 63 61 6e 6e 6f 74 20 66 72 65 65 0a 2a 2a 20 73  cannot free.** s
1c060 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c070 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
1c080 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
1c090 20 65 78 63 65 65 64 65 64 2c 20 74 68 65 20 6d   exceeded, the m
1c0a0 65 6d 6f 72 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f  emory is.** allo
1c0b0 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
1c0c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
1c0d0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
1c0e0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1c0f0 73 68 75 74 74 69 6e 67 20 64 6f 77 6e 20 61 20  shutting down a 
1c100 74 68 72 65 61 64 20 73 71 6c 69 74 65 33 5f 73  thread sqlite3_s
1c110 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
1c120 20 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20   must be set to 
1c130 0a 2a 2a 20 7a 65 72 6f 20 28 74 68 65 20 64 65  .** zero (the de
1c140 66 61 75 6c 74 29 20 6f 72 20 65 6c 73 65 20 74  fault) or else t
1c150 68 65 20 74 68 72 65 61 64 20 77 69 6c 6c 20 6c  he thread will l
1c160 65 61 6b 20 6d 65 6d 6f 72 79 2e 20 41 6c 74 65  eak memory. Alte
1c170 72 6e 61 74 69 76 65 6c 79 2c 20 75 73 65 0a 2a  rnatively, use.*
1c180 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  * the [sqlite3_t
1c190 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d  hread_cleanup()]
1c1a0 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65   API..**.** A ne
1c1b0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
1c1c0 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
1c1d0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
1c1e0 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
1c1f0 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
1c200 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
1c210 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
1c220 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
1c230 6f 72 79 20 69 73 20 65 78 68 61 75 73 65 64 2e  ory is exhaused.
1c240 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1c250 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
1c260 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
1c270 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
1c280 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
1c290 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
1c2a0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
1c2b0 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74  imit.  But if it
1c2c0 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  .** is unable to
1c2d0 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
1c2e0 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73  sage below the s
1c2f0 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75  oft limit, execu
1c300 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
1c310 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
1c320 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
1c330 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
1c340 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a  y the limit is .
1c350 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66  ** called a "sof
1c360 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73  t" limit.  It is
1c370 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
1c380 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
1c390 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
1c3a0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
1c3b0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
1c3c0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
1c3d0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
1c3e0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6f  ORY_MANAGEMENT o
1c3f0 70 74 69 6f 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65  ption set..** me
1c400 6d 6f 72 79 2d 6d 61 6e 61 67 65 6d 65 6e 74 20  mory-management 
1c410 68 61 73 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  has been enabled
1c420 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1c430 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
1c440 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
1c450 41 50 49 33 52 45 46 3a 20 20 43 6c 65 61 6e 20  API3REF:  Clean 
1c460 55 70 20 54 68 72 65 61 64 20 4c 6f 63 61 6c 20  Up Thread Local 
1c470 53 74 6f 72 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68  Storage.**.** Th
1c480 69 73 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  is routine makes
1c490 20 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 74   sure that all t
1c4a0 68 72 65 61 64 2d 6c 6f 63 61 6c 20 73 74 6f 72  hread-local stor
1c4b0 61 67 65 20 68 61 73 20 62 65 65 6e 0a 2a 2a 20  age has been.** 
1c4c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20  deallocated for 
1c4d0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
1c4e0 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ad..**.** This r
1c4f0 6f 75 74 69 6e 65 20 69 73 20 6e 6f 74 20 74 65  outine is not te
1c500 63 68 6e 69 63 61 6c 6c 79 20 6e 65 63 65 73 73  chnically necess
1c510 61 72 79 2e 20 20 41 6c 6c 20 74 68 72 65 61 64  ary.  All thread
1c520 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 0a 2a  -local storage.*
1c530 2a 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  * will be automa
1c540 74 69 63 61 6c 6c 79 20 64 65 61 6c 6c 6f 63 61  tically dealloca
1c550 74 65 64 20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d  ted once memory-
1c560 6d 61 6e 61 67 65 6d 65 6e 74 20 61 6e 64 0a 2a  management and.*
1c570 2a 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 61  * shared-cache a
1c580 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  re disabled and 
1c590 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1c5a0 6d 69 74 20 68 61 73 20 62 65 65 6e 20 73 65 74  mit has been set
1c5b0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2e 20 20 54 68  .** to zero.  Th
1c5c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
1c5d0 6f 76 69 64 65 64 20 61 73 20 61 20 63 6f 6e 76  ovided as a conv
1c5e0 65 6e 69 65 6e 63 65 20 66 6f 72 20 75 73 65 72  enience for user
1c5f0 73 20 77 68 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f  s who.** want to
1c600 20 6d 61 6b 65 20 61 62 73 6f 6c 75 74 65 6c 79   make absolutely
1c610 20 73 75 72 65 20 74 68 65 79 20 68 61 76 65 20   sure they have 
1c620 6e 6f 74 20 66 6f 72 67 6f 74 74 65 6e 20 73 6f  not forgotten so
1c630 6d 65 74 68 69 6e 67 0a 2a 2a 20 70 72 69 6f 72  mething.** prior
1c640 20 74 6f 20 6b 69 6c 6c 69 6e 67 20 6f 66 66 20   to killing off 
1c650 61 20 74 68 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69  a thread..*/.voi
1c660 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
1c670 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
1c680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c690 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61    Extract Metada
1c6a0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
1c6b0 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
1c6c0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a  ** This routine.
1c6d0 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d  ** returns meta-
1c6e0 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
1c6f0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
1c700 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62  a specific datab
1c710 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63  ase.** table acc
1c720 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
1c730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  e connection han
1c740 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68  dle passed as th
1c750 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
1c760 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   .** argument..*
1c770 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20  *.** The column 
1c780 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1c790 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
1c7a0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
1c7b0 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20  rameters to .** 
1c7c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
1c7d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c7e0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
1c7f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1c800 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
1c810 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f  "main", "temp" o
1c820 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
1c830 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
1c840 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
1c850 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
1c860 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  L. If it is NULL
1c870 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
1c880 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
1c890 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
1c8a0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
1c8b0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
1c8c0 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61  ithm as the data
1c8d0 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73  base engine uses
1c8e0 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20   to .** resolve 
1c8f0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
1c900 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
1c910 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
1c920 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
1c930 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
1c940 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
1c950 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a  le and column .*
1c960 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
1c970 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
1c980 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
1c990 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
1c9a0 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20  ameters .** may 
1c9b0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d  be NULL..**.** M
1c9c0 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  eta information 
1c9d0 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77  is returned by w
1c9e0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65  riting to the me
1c9f0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70  mory locations p
1ca00 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
1ca10 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65  5th and subseque
1ca20 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  nt parameters to
1ca30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
1ca40 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a  Any of these .**
1ca50 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
1ca60 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  e NULL, in which
1ca70 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
1ca80 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
1ca90 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f  of meta .** info
1caa0 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74  rmation is ommit
1cab0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ted..**.** <pre>
1cac0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20  .** Parameter   
1cad0 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20    Output Type   
1cae0 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a     Description.*
1caf0 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  * --------------
1cb00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb10 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74  -----.**.**   5t
1cb20 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
1cb30 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20  char*      Data 
1cb40 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20  type.**   6th   
1cb50 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
1cb60 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74  *      Name of t
1cb70 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  he default colla
1cb80 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a  tion sequence .*
1cb90 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20  *   7th         
1cba0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
1cbb0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
1cbc0 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
1cbd0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
1cbe0 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69     8th         i
1cbf0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1cc00 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1cc10 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
1cc20 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
1cc30 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69     9th         i
1cc40 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
1cc50 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
1cc60 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
1cc70 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  ENT.** </pre>.**
1cc80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
1cc90 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
1cca0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
1ccb0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
1ccc0 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c  for the .** decl
1ccd0 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
1cce0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1ccf0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
1cd00 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
1cd10 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79   .** call to any
1cd20 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63   sqlite API func
1cd30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tion..**.** If t
1cd40 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
1cd50 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
1cd60 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65   view, then an e
1cd70 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1cd80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
1cd90 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
1cda0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
1cdb0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
1cdc0 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45  nd an .** INTEGE
1cdd0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  R PRIMARY KEY co
1cde0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
1cdf0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1ce00 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
1ce10 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ut .** parameter
1ce20 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
1ce30 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
1ce40 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
1ce50 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
1ce60 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
1ce70 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20  red IPK column, 
1ce80 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
1ce90 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
1cea0 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  et as .** follow
1ceb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
1cec0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
1ced0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
1cee0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
1cef0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
1cf00 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
1cf10 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
1cf20 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
1cf30 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
1cf40 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
1cf50 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
1cf60 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
1cf70 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
1cf80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
1cf90 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
1cfa0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
1cfb0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
1cfc0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
1cfd0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
1cfe0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
1cff0 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72  nd, an SQLITE er
1d000 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
1d010 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
1d020 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66  r message.** lef
1d030 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  t in the databas
1d040 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20  e handle (to be 
1d050 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
1d060 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d070 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  )..**.** This AP
1d080 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
1d090 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
1d0a0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
1d0b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
1d0c0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1d0d0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
1d0e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1d0f0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
1d100 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
1d110 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
1d120 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1d130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
1d140 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
1d150 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1d160 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
1d170 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
1d180 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
1d190 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
1d1a0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
1d1b0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
1d1c0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
1d1d0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
1d1e0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
1d1f0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
1d200 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
1d210 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
1d220 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
1d230 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
1d240 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
1d250 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
1d260 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
1d270 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
1d280 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1d290 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
1d2a0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
1d2b0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
1d2c0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
1d2d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
1d2e0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
1d2f0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
1d300 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
1d310 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
1d320 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
1d330 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61  e if colums is a
1d340 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
1d350 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1d360 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
1d370 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74  ension.**.** Att
1d380 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20  empt to load an 
1d390 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
1d3a0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
1d3b0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a  ed in the file.*
1d3c0 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e  * zFile.  The en
1d3d0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
1d3e0 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62  oc.  zProc may b
1d3f0 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  e 0 in which cas
1d400 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  e the.** name of
1d410 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
1d420 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
1d430 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
1d440 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74  init"..**.** Ret
1d450 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1d460 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
1d470 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
1d480 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
1d490 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  wrong..**.** If 
1d4a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1d4b0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
1d4c0 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c  not 0, then fill
1d4d0 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
1d4e0 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67  .** error messag
1d4f0 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c  e text.  The cal
1d500 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
1d510 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
1d520 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
1d530 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1d540 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65  e()]..**.** Exte
1d550 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
1d560 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
1d570 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1d580 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
1d590 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74  on()].** prior t
1d5a0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
1d5b0 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77  PI or an error w
1d5c0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
1d5d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d5e0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
1d5f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d600 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
1d610 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
1d620 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
1d630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
1d640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
1d650 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
1d660 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
1d670 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
1d680 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
1d690 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
1d6a0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
1d6b0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
1d6c0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
1d6d0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
1d6e0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
1d6f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
1d700 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
1d710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d720 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
1d730 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
1d740 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f  Loading.**.** So
1d750 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
1d760 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
1d770 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
1d780 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
1d790 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
1d7a0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
1d7b0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
1d7c0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
1d7d0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
1d7e0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
1d7f0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
1d800 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
1d810 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  the following.**
1d820 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64   API is provided
1d830 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
1d840 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1d850 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
1d860 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e  m on and.** off.
1d870 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64    It is off by d
1d880 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63  efault.  See tic
1d890 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a  ket #1863..**.**
1d8a0 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   Call this routi
1d8b0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
1d8c0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
1d8d0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a  on loading on.**
1d8e0 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
1d8f0 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
1d900 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  rn it back off a
1d910 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
1d920 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
1d930 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
1d940 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
1d950 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1d960 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67  REF: Make Arrang
1d970 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61  ements To Automa
1d980 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
1d990 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
1d9a0 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65  Register an exte
1d9b0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
1d9c0 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
1d9d0 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
1d9e0 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
1d9f0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1da00 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is opened 
1da10 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1da20 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
1da30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1da40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
1da50 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
1da60 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
1da70 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
1da80 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
1da90 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
1daa0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
1dab0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
1dac0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
1dad0 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65  all new database
1dae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a   connections..**
1daf0 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78  .** Duplicate ex
1db00 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74  tensions are det
1db10 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67  ected so calling
1db20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
1db30 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
1db40 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
1db50 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
1db60 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ess..**.** This 
1db70 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
1db80 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1db90 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
1dba0 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73  array.** that is
1dbb0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d   obtained from m
1dbc0 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75  alloc().  If you
1dbd0 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
1dbe0 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e  ak.** checker on
1dbf0 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
1dc00 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
1dc10 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
1dc20 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68  his.** array, th
1dc30 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  en invoke [sqlit
1dc40 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74  e3_automatic_ext
1dc50 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20  ension_reset()] 
1dc60 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74  prior.** to shut
1dc70 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65  down to free the
1dc80 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41   memory..**.** A
1dc90 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1dca0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
1dcb0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a   all threads..**
1dcc0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1dcd0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1dce0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
1dcf0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
1dd00 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
1dd10 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
1dd20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
1dd30 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
1dd40 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74  nsion(void *xEnt
1dd50 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a  ryPoint);.../*.*
1dd60 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1dd70 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
1dd80 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
1dd90 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20  .** Disable all 
1dda0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1ddb0 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20  tered automatic 
1ddc0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69  extensions.  Thi
1ddd0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  s.** routine und
1dde0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
1ddf0 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c  f all prior [sql
1de00 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65  ite3_automatic_e
1de10 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
1de20 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  alls..**.** This
1de30 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61   call disabled a
1de40 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
1de50 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
1de60 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ds..**.** This i
1de70 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
1de80 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1de90 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1dea0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
1deb0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1dec0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
1ded0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1dee0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
1def0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
1df00 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
1df10 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
1df20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
1df30 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
1df40 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
1df50 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
1df60 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1df70 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
1df80 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
1df90 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
1dfa0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
1dfb0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
1dfc0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
1dfd0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
1dfe0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
1dff0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
1e000 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
1e010 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
1e020 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1e030 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
1e040 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
1e050 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
1e060 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
1e070 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
1e080 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
1e090 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
1e0a0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
1e0b0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
1e0c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
1e0d0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
1e0e0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
1e0f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1e100 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
1e110 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
1e120 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
1e130 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
1e140 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
1e150 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1e160 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
1e170 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
1e180 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1e190 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
1e1a0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
1e1b0 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69  /*.** A module i
1e1c0 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72  s a class of vir
1e1d0 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61  tual tables.  Ea
1e1e0 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66  ch module is def
1e1f0 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e  ined.** by an in
1e200 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
1e210 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
1e220 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75  e.  This structu
1e230 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d  re consists.** m
1e240 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
1e250 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
1e260 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
1e270 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
1e280 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
1e290 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
1e2a0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
1e2b0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
1e2c0 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
1e2d0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
1e2e0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
1e2f0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
1e300 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
1e310 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
1e320 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
1e330 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
1e340 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
1e350 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
1e360 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
1e370 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
1e380 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
1e390 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
1e3a0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
1e3b0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1e3c0 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
1e3d0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
1e3e0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
1e3f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1e400 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
1e410 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
1e420 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1e430 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
1e440 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
1e450 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
1e460 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
1e470 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
1e480 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
1e490 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
1e4a0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
1e4b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
1e4c0 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
1e4d0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
1e4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e4f0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
1e500 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
1e510 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
1e520 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1e530 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
1e540 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
1e550 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
1e560 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
1e570 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
1e580 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
1e590 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
1e5a0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
1e5b0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
1e5c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1e5d0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
1e5e0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
1e5f0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
1e600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
1e610 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
1e620 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
1e630 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
1e640 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
1e650 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
1e660 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1e670 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
1e680 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
1e690 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
1e6a0 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
1e6b0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
1e6c0 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
1e6d0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
1e6e0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
1e6f0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
1e700 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
1e710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
1e720 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
1e730 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
1e740 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
1e750 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
1e760 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
1e770 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e   **ppArg);..  in
1e780 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
1e790 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
1e7a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1e7b0 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ew);.};../*.** T
1e7c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
1e7d0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
1e7e0 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
1e7f0 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
1e800 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
1e810 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
1e820 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
1e830 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
1e840 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
1e850 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
1e860 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
1e870 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
1e880 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
1e890 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
1e8a0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
1e8b0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
1e8c0 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
1e8d0 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
1e8e0 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
1e8f0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
1e900 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
1e910 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
1e920 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
1e930 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
1e940 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
1e950 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
1e960 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
1e970 73 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f  s =, <, <=, >, o
1e980 72 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69  r >=.  The parti
1e990 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
1e9a0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1e9b0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
1e9c0 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
1e9d0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
1e9e0 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
1e9f0 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
1ea00 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
1ea10 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
1ea20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
1ea30 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
1ea40 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
1ea50 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
1ea60 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
1ea70 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
1ea80 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
1ea90 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
1eaa0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
1eab0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
1eac0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
1ead0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
1eae0 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
1eaf0 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
1eb00 74 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45  tinos to the WHE
1eb10 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
1eb20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
1eb30 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
1eb40 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
1eb50 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
1eb60 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
1eb70 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
1eb80 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
1eb90 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
1eba0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
1ebb0 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
1ebc0 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
1ebd0 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
1ebe0 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
1ebf0 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
1ec00 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
1ec10 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
1ec20 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
1ec30 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
1ec40 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
1ec50 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
1ec60 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
1ec70 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
1ec80 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
1ec90 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
1eca0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
1ecb0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
1ecc0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
1ecd0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
1ece0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
1ecf0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
1ed00 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
1ed10 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
1ed20 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
1ed30 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
1ed40 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
1ed50 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
1ed60 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
1ed70 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
1ed80 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
1ed90 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
1eda0 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
1edb0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
1edc0 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
1edd0 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
1ede0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
1edf0 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
1ee00 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
1ee10 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
1ee20 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
1ee30 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
1ee40 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
1ee50 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
1ee60 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
1ee70 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
1ee80 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
1ee90 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
1eea0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
1eeb0 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
1eec0 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
1eed0 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
1eee0 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
1eef0 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
1ef00 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
1ef10 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
1ef20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
1ef30 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
1ef40 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
1ef50 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1ef60 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
1ef70 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
1ef80 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
1ef90 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
1efa0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
1efb0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
1efc0 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
1efd0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
1efe0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
1eff0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
1f000 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
1f010 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
1f020 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
1f030 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
1f040 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
1f050 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
1f060 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
1f070 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
1f080 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
1f090 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20  straint;     /* 
1f0a0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
1f0b0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
1f0c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75   */.  const stru
1f0d0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
1f0e0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
1f0f0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
1f100 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f110 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
1f120 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
1f130 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
1f140 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
1f150 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
1f160 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
1f170 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
1f180 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
1f190 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
1f1a0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
1f1b0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
1f1c0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
1f1d0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
1f1e0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
1f1f0 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
1f200 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63  ignore */.  } *c
1f210 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
1f220 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  ;      /* Table 
1f230 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
1f240 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
1f250 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65   const int nOrde
1f260 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e  rBy;        /* N
1f270 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1f280 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
1f290 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  lause */.  const
1f2a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f2b0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
1f2c0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
1f2d0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
1f2e0 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
1f2f0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
1f300 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
1f310 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
1f320 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
1f330 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73  SC. */.  } *cons
1f340 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t aOrderBy;     
1f350 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
1f360 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20   BY clause */.. 
1f370 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
1f380 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f390 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
1f3a0 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
1f3b0 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
1f3c0 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
1f3d0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
1f3e0 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
1f3f0 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
1f400 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
1f410 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
1f420 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
1f430 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
1f440 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43  */.  } *const aC
1f450 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a  onstraintUsage;.
1f460 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20    int idxNum;   
1f470 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f480 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69  Number used to i
1f490 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65  dentify the inde
1f4a0 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78  x */.  char *idx
1f4b0 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
1f4c0 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73    /* String, pos
1f4d0 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  sibly obtained f
1f4e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f4f0 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64  oc */.  int need
1f500 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20  ToFreeIdxStr;   
1f510 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74     /* Free idxSt
1f520 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  r using sqlite3_
1f530 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a  free() if true *
1f540 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /.  int orderByC
1f550 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
1f560 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
1f570 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
1f580 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20  red */.  double 
1f590 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20  estimatedCost;  
1f5a0 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64      /* Estimated
1f5b0 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74   cost of using t
1f5c0 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a  his index */.};.
1f5d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1f5e0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
1f5f0 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
1f600 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
1f610 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
1f620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1f630 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
1f640 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20  LE    8.#define 
1f650 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
1f660 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
1f670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f680 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
1f690 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e  _GE    32.#defin
1f6a0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
1f6b0 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
1f6c0 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  64../*.** This r
1f6d0 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
1f6e0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
1f6f0 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74   module name wit
1f700 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63  h an SQLite.** c
1f710 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75  onnection.  Modu
1f720 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
1f730 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
1f740 72 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a  re creating new.
1f750 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
1f760 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c  s on the module,
1f770 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67   or before using
1f780 20 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72   preexisting vir
1f790 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f  tual.** tables o
1f7a0 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f  f the module..*/
1f7b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
1f7c0 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
1f7d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f7e0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
1f7f0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
1f800 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
1f810 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
1f820 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
1f830 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1f840 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
1f850 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
1f860 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d  odule *,    /* M
1f870 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
1f880 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
1f890 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *               
1f8a0 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
1f8b0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
1f8c0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
1f8d0 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ./*.** This rout
1f8e0 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ine is identical
1f8f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1f900 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
1f910 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a  method above,.**
1f920 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1f930 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63  allows a destruc
1f940 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  tor function to 
1f950 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74  be specified. It
1f960 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65   is.** even more
1f970 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68   experimental th
1f980 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74  an the rest of t
1f990 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1f9a0 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s API..*/.int sq
1f9b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
1f9c0 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ule_v2(.  sqlite
1f9d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1f9e0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
1f9f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
1fa00 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
1fa10 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
1fa20 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
1fa30 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
1fa40 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
1fa50 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
1fa60 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
1fa70 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
1fa80 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  e */.  void *,  
1fa90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1faa0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
1fab0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
1fac0 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28  nnect */.  void(
1fad0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
1fae0 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20  )     /* Module 
1faf0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
1fb00 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ion */.);../*.**
1fb10 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
1fb20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
1fb30 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
1fb40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1fb50 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
1fb60 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
1fb70 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
1fb80 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
1fb90 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
1fba0 2a 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74  ** be taylored t
1fbb0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
1fbc0 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
1fbd0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1fbe0 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70  n.   The.** purp
1fbf0 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
1fc00 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
1fc10 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
1fc20 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d  ds that are comm
1fc30 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64  on.** to all mod
1fc40 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
1fc50 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ons..**.** Virtu
1fc60 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
1fc70 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
1fc80 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
1fc90 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
1fca0 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
1fcb0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
1fcc0 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  f() to zErrMsg. 
1fcd0 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
1fce0 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
1fcf0 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
1fd00 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
1fd10 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  y a call to sqli
1fd20 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72  te3_free().** pr
1fd30 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
1fd40 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
1fd50 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72   zErrMsg.  After
1fd60 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1fd70 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
1fd80 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
1fd90 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
1fda0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
1fdb0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
1fdc0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
1fdd0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
1fde0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
1fdf0 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
1fe00 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74  d.  Note.** that
1fe10 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1fe20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66  () and sqlite3_f
1fe30 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f  ree() are used o
1fe40 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  n the zErrMsg fi
1fe50 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72  eld.** since vir
1fe60 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20  tual tables are 
1fe70 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65  commonly impleme
1fe80 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65  nted in loadable
1fe90 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63   extensions whic
1fea0 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65  h.** do not have
1feb0 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74   access to sqlit
1fec0 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73  e3MPrintf() or s
1fed0 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f  qlite3Free()..*/
1fee0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
1fef0 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
1ff00 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
1ff10 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
1ff20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
1ff30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
1ff40 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
1ff50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ff60 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
1ff70 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20  nally */.  char 
1ff80 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20  *zErrMsg;       
1ff90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
1ffa0 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d  ror message from
1ffb0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1ffc0 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  () */.  /* Virtu
1ffd0 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1ffe0 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
1fff0 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
20000 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
20010 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f  .};../* Every mo
20020 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
20030 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
20040 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
20050 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
20060 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
20070 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
20080 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
20090 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
200a0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
200b0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
200c0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
200d0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
200e0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
200f0 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
20100 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
20110 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
20120 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
20130 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
20140 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
20150 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
20160 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
20170 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
20180 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
20190 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
201a0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
201b0 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
201c0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
201d0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
201e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
201f0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
20200 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
20210 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
20220 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
20230 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
20240 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
20250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
20260 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
20270 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
20280 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
20290 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64   The xCreate and
202a0 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
202b0 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73  s of a module us
202c0 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
202d0 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  API.** to declar
202e0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
202f0 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
20300 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
20310 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
20320 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
20330 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
20340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
20350 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
20360 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
20370 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
20380 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  ./*.** Virtual t
20390 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
203a0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
203b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
203c0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
203d0 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
203e0 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
203f0 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
20400 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
20410 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
20420 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
20430 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
20440 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
20450 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
20460 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
20470 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
20480 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
20490 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
204a0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
204b0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
204c0 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
204d0 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
204e0 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
204f0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
20500 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
20510 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
20520 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
20530 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
20540 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
20550 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
20560 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
20570 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
20580 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
20590 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
205a0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
205b0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f  to be a place-ho
205c0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
205d0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
205e0 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
205f0 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
20600 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
20610 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
20620 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
20630 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
20640 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
20650 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
20660 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
20670 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
20680 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
20690 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
206a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
206b0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
206c0 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
206d0 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
206e0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
206f0 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
20700 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
20710 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
20720 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
20730 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
20740 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
20750 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
20760 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
20770 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
20780 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
20790 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
207a0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
207b0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
207c0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
207d0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
207e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
207f0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
20800 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
20810 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
20820 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
20830 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
20840 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
20850 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
20860 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
20870 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  .**.****** EXPER
20880 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
20890 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
208a0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
208b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a  *********.*/../*
208c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20  .** CAPI3REF: A 
208d0 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65  Handle To An Ope
208e0 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20  n BLOB.**.** An 
208f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
20900 66 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65  following opaque
20910 20 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73   structure is us
20920 65 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73  ed to .** repres
20930 65 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64  ent an blob-hand
20940 6c 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64  le.  A blob-hand
20950 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
20960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
20970 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65  b_open()] and de
20980 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
20990 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
209a0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
209b0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
209c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
209d0 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
209e0 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
209f0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
20a00 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
20a10 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ections of the b
20a20 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  lob..** The [sql
20a30 74 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29  tie3_blob_size()
20a40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
20a50 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
20a60 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
20a70 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
20a80 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
20a90 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
20aa0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
20ab0 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
20ac0 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
20ad0 49 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61  I/O.**.** Open a
20ae0 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62   handle to the b
20af0 6c 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72  lob located in r
20b00 6f 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e  ow iRow,, column
20b10 20 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61   zColumn, .** ta
20b20 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
20b30 74 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e  tabase zDb. i.e.
20b40 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74   the same blob t
20b50 68 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20  hat would.** be 
20b60 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
20b70 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
20b80 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
20b90 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
20ba0 48 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f  HERE rowid = iRo
20bb0 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  w;.** </pre>.**.
20bc0 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20  ** If the flags 
20bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
20be0 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20  -zero, the blob 
20bf0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a  is opened for .*
20c00 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  * read and write
20c10 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69   access. If it i
20c20 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62  s zero, the blob
20c30 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
20c40 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a  ead .** access..
20c50 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
20c60 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
20c70 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
20c80 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74  e new .** [sqlit
20c90 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68  e3_blob | blob h
20ca0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
20cb0 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a  n to *ppBlob..**
20cc0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   Otherwise an er
20cd0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
20ce0 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79  rned and .** any
20cf0 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74   value written t
20d00 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64  o *ppBlob should
20d10 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
20d20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54  the caller..** T
20d30 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
20d40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68  s the database-h
20d50 61 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65  andle error code
20d60 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
20d70 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
20d80 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
20d90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20da0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
20db0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
20dc0 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
20dd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
20de0 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
20df0 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
20e00 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
20e10 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
20e20 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
20e30 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
20e40 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
20e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20e60 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
20e70 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  ndle.**.** Close
20e80 20 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65   an open [sqlite
20e90 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
20ea0 6e 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndle]..*/.int sq
20eb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
20ec0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
20ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20ee0 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53  F:  Return The S
20ef0 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
20f00 4c 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  LOB.**.** Return
20f10 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
20f20 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61  es of the blob a
20f30 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
20f40 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  e open .** [sqli
20f50 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
20f60 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
20f70 73 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  s an argument..*
20f80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
20f90 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
20fa0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
20fb0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
20fc0 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
20fd0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
20fe0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
20ff0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
21000 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
21010 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
21020 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
21030 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61  andle] into a ca
21040 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  ller supplied bu
21050 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
21060 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
21070 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a  ied into buffer.
21080 2a 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70  ** z from the op
21090 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e  en blob, startin
210a0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
210b0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  set..**.** On su
210c0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
210d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
210e0 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
210f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
21100 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
21110 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
21120 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
21130 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
21140 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
21150 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
21160 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
21170 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
21180 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
21190 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
211a0 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74   CAPI3REF:  Writ
211b0 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
211c0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
211d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
211e0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
211f0 77 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20  write data into 
21200 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  an open .** [sql
21210 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
21220 2d 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20  -handle] from a 
21230 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75  user supplied bu
21240 66 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73  ffer..** n bytes
21250 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
21260 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66  ied from the buf
21270 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  fer.** pointed t
21280 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20  o by z into the 
21290 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74  open blob, start
212a0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
212b0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ffset..**.** If 
212c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
212d0 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
212e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
212f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
21300 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20   was not opened 
21310 66 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65  for writing (the
21320 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21330 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
21340 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61  b_open()].*** wa
21350 73 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75  s zero), this fu
21360 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
21370 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
21380 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
21390 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d  ction may only m
213a0 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e  odify the conten
213b0 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20  ts of the blob, 
213c0 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73  it is.** not pos
213d0 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73  sible to increas
213e0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
213f0 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20  blob using this 
21400 41 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65  API. If.** offse
21410 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
21420 73 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66  s than n bytes f
21430 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
21440 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51  he blob, .** [SQ
21450 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
21460 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
21470 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
21480 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
21490 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
214a0 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69  eturned. Otherwi
214b0 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49  se, an .** [SQLI
214c0 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74  TE_ERROR | SQLit
214d0 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72  e error code] or
214e0 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   an.** [SQLITE_I
214f0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
21500 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
21510 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   is returned..*/
21520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
21530 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
21540 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
21550 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
21560 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
21570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69  ** CAPI3REF:  Vi
21580 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
21590 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20  m Objects.**.** 
215a0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79  A virtual filesy
215b0 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e  stem (VFS) is an
215c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
215d0 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51  bject.** that SQ
215e0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74  Lite uses to int
215f0 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68  eract.** with th
21600 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
21610 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
21620 4d 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65  Most builds come
21630 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
21640 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
21650 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
21660 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
21670 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
21680 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
21690 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
216a0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
216b0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
216c0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
216d0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
216e0 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
216f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 64  The sqlite3_find
21700 5f 76 66 73 28 29 20 69 6e 74 65 72 66 61 63 65  _vfs() interface
21710 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
21720 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
21730 6e 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20  n its.** name.  
21740 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
21750 65 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68  ensitive.  If th
21760 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
21770 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
21780 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
21790 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20   If zVfsName is 
217a0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
217b0 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73  fault .** VFS is
217c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
217d0 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
217e0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
217f0 71 6c 69 74 65 33 5f 72 65 67 69 73 74 65 72 5f  qlite3_register_
21800 76 66 73 28 29 2e 20 20 45 61 63 68 0a 2a 2a 20  vfs().  Each.** 
21810 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20  new VFS becomes 
21820 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
21830 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  if the makeDflt 
21840 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20  flag is set..** 
21850 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
21860 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
21870 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
21880 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
21890 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73   To make an exis
218a0 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
218b0 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
218c0 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
218d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
218e0 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 0a  eDflt flag set..
218f0 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  ** .** Unregiste
21900 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
21910 20 73 71 6c 69 74 65 33 5f 75 6e 72 65 67 69 73   sqlite3_unregis
21920 74 65 72 5f 76 66 73 28 29 20 69 6e 74 65 72 66  ter_vfs() interf
21930 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
21940 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
21950 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
21960 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
21970 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
21980 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
21990 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
219a0 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
219b0 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73  /.sqlite3_vfs *s
219c0 71 6c 69 74 65 33 5f 66 69 6e 64 5f 76 66 73 28  qlite3_find_vfs(
219d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
219e0 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Name);.int sqlit
219f0 65 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28  e3_register_vfs(
21a00 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
21a10 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74  t makeDflt);.int
21a20 20 73 71 6c 69 74 65 33 5f 75 6e 72 65 67 69 73   sqlite3_unregis
21a30 74 65 72 5f 76 66 73 28 73 71 6c 69 74 65 33 5f  ter_vfs(sqlite3_
21a40 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  vfs*);../*.** CA
21a50 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a  PI3REF: Mutexes.
21a60 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
21a70 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
21a80 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68   routines for th
21a90 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e  read.** synchron
21aa0 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68  ization.  Though
21ab0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64   they are intend
21ac0 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  ed for internal.
21ad0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
21ae0 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b  , code that link
21af0 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65  s against SQLite
21b00 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64   is.** permitted
21b10 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74   to use any of t
21b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
21b30 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
21b40 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74  source code cont
21b50 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ains multiple im
21b60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a  plementations .*
21b70 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
21b80 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 63   routines that c
21b90 61 6e 20 62 65 20 73 65 6c 65 63 74 65 64 20 61  an be selected a
21ba0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  t compile-time.*
21bb0 2a 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 6e  * by defining on
21bc0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
21bd0 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
21be0 72 20 6d 61 63 72 6f 73 3a 0a 2a 2a 0a 2a 2a 20  r macros:.**.** 
21bf0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  <ul>.** <li>   S
21c00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
21c10 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
21c20 4c 49 54 45 5f 4d 55 54 45 58 5f 57 49 4e 33 32  LITE_MUTEX_WIN32
21c30 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
21c40 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
21c50 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
21c60 54 45 58 5f 41 50 50 44 45 46 0a 2a 2a 20 3c 2f  TEX_APPDEF.** </
21c70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f 6e  ul>.**.** If non
21c80 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 6d  e of the above m
21c90 61 63 72 6f 73 20 69 73 20 64 65 66 69 6e 65 64  acros is defined
21ca0 2c 20 74 68 65 20 63 6f 64 65 20 75 73 65 73 0a  , the code uses.
21cb0 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 69 6d 70  ** a default imp
21cc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
21cd0 2a 20 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  * .** The SQLITE
21ce0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c  _MUTEX_NOOP impl
21cf0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20  ementation is a 
21d00 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  set of routines 
21d10 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
21d20 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e   real locking an
21d30 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  d is appropriate
21d40 20 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20   for use in .** 
21d50 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  a single-threade
21d60 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  d application..*
21d70 2a 20 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  * .** If the SQL
21d80 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
21d90 20 69 73 20 64 65 66 69 6e 65 64 2c 20 74 68 65   is defined, the
21da0 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  n no mutex.** im
21db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
21dc0 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68  included with th
21dd0 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a  e library.  The.
21de0 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61  ** mutex interfa
21df0 63 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  ce routines defi
21e00 6e 65 64 20 61 62 6f 76 65 20 61 72 65 20 65 78  ned above are ex
21e10 74 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65  ternal.** refere
21e20 6e 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69  nces in the SQLi
21e30 74 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77  te library for w
21e40 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hich implementat
21e50 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ions.** must be 
21e60 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
21e70 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  application..**.
21e80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
21e90 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
21ea0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
21eb0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
21ec0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
21ed0 74 65 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69  ter to it.  If i
21ee0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a  t returns NULL.*
21ef0 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61  * that means tha
21f00 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20  t a mutex could 
21f10 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  not be allocated
21f20 2e 20 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  .  SQLite.** wil
21f30 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61  l unwind its sta
21f40 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ck and return an
21f50 20 65 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67   error.  The arg
21f60 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
21f70 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
21f80 29 20 69 73 20 75 73 75 61 6c 6c 79 20 7a 65 72  ) is usually zer
21f90 6f 2c 20 77 68 69 63 68 20 63 61 75 73 65 73 0a  o, which causes.
21fa0 2a 2a 20 61 6e 79 20 73 70 61 63 65 20 72 65 71  ** any space req
21fb0 75 69 72 65 64 20 66 6f 72 20 74 68 65 20 6d 75  uired for the mu
21fc0 74 65 78 20 74 6f 20 62 65 20 6f 62 74 61 69 6e  tex to be obtain
21fd0 65 64 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ed from.** sqlit
21fe0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2e 20 20 48 6f  e3_malloc().  Ho
21ff0 77 65 76 65 72 20 69 66 20 74 68 65 20 61 72 67  wever if the arg
22000 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 73 69 74  ument is a posit
22010 69 76 65 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6c  ive.** integer l
22020 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
22030 6c 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  l to SQLITE_MUTE
22040 58 5f 53 54 41 54 49 43 5f 4d 41 58 2c 20 74 68  X_STATIC_MAX, th
22050 65 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  en a pointer.** 
22060 74 6f 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  to a static mute
22070 78 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  x is returned.  
22080 54 68 65 72 65 20 61 72 65 20 61 20 66 69 6e 69  There are a fini
22090 74 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  te number.** of 
220a0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20  static mutexes. 
220b0 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   Static mutexes 
220c0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 70 61  should not be pa
220d0 73 73 65 64 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ssed.** to sqlit
220e0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 2e  e3_mutex_free().
220f0 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
22100 20 61 72 65 20 75 73 65 64 20 69 6e 74 65 72 6e   are used intern
22110 61 6c 6c 79 0a 2a 2a 20 62 79 20 74 68 65 20 53  ally.** by the S
22120 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 73  QLite core and s
22130 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
22140 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
22150 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
22160 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
22170 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
22180 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
22190 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
221a0 65 64 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74  ed mutex.  SQLit
221b0 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
221c0 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
221d0 0a 2a 2a 20 6d 75 74 65 78 20 74 68 61 74 20 69  .** mutex that i
221e0 74 20 61 6c 6c 6f 63 61 74 65 73 2e 0a 2a 2a 0a  t allocates..**.
221f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
22200 75 74 65 78 5f 65 6e 74 65 72 28 29 20 72 6f 75  utex_enter() rou
22210 74 69 6e 65 20 61 74 74 65 6d 70 74 73 20 74 6f  tine attempts to
22220 20 65 6e 74 65 72 20 61 0a 2a 2a 20 6d 75 74 65   enter a.** mute
22230 78 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74  x.  If another t
22240 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
22250 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
22260 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
22270 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
22280 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
22290 55 53 59 20 69 66 20 62 6c 6f 63 6b 46 6c 61 67  USY if blockFlag
222a0 0a 2a 2a 20 69 73 20 7a 65 72 6f 2c 20 6f 72 20  .** is zero, or 
222b0 69 74 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  it will block an
222c0 64 20 77 61 69 74 20 66 6f 72 20 74 68 65 20 6f  d wait for the o
222d0 74 68 65 72 20 74 68 72 65 61 64 20 74 6f 0a 2a  ther thread to.*
222e0 2a 20 65 78 69 74 20 69 66 20 62 6c 6f 63 6b 46  * exit if blockF
222f0 6c 61 67 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e  lag is non-zero.
22300 20 20 4d 75 74 65 78 65 73 20 61 72 65 20 72 65    Mutexes are re
22310 63 75 72 73 69 76 65 2e 20 20 54 68 65 0a 2a 2a  cursive.  The.**
22320 20 73 61 6d 65 20 74 68 72 65 61 64 20 63 61 6e   same thread can
22330 20 65 6e 74 65 72 20 61 20 73 69 6e 67 6c 65 20   enter a single 
22340 6d 75 74 65 78 20 6d 75 6c 74 69 70 6c 65 20 74  mutex multiple t
22350 69 6d 65 73 2e 20 20 45 61 63 68 0a 2a 2a 20 65  imes.  Each.** e
22360 6e 74 72 61 6e 63 65 20 6d 75 73 74 20 62 65 20  ntrance must be 
22370 6d 61 74 63 68 65 64 20 77 69 74 68 20 61 20 63  matched with a c
22380 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 78 69  orresponding exi
22390 74 20 62 65 66 6f 72 65 0a 2a 2a 20 61 6e 6f 74  t before.** anot
223a0 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 62  her thread is ab
223b0 6c 65 20 74 6f 20 65 6e 74 65 72 20 74 68 65 20  le to enter the 
223c0 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  mutex..**.** The
223d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
223e0 78 69 74 28 29 20 72 6f 75 74 69 6e 65 20 65 78  xit() routine ex
223f0 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74  its a mutex that
22400 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
22410 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
22420 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20  e same thread.  
22430 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
22440 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
22450 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
22460 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
22470 65 64 20 6f 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  ed or.** is not 
22480 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
22490 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ted.  SQLite wil
224a0 6c 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  l never do eithe
224b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
224c0 69 74 65 33 5f 6d 75 74 65 78 5f 73 65 72 69 61  ite3_mutex_seria
224d0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
224e0 73 20 75 73 65 64 20 74 6f 20 73 65 72 69 61 6c  s used to serial
224f0 69 7a 65 20 0a 2a 2a 20 61 20 73 75 62 72 6f 75  ize .** a subrou
22500 74 69 6e 65 2e 20 20 54 68 65 20 73 75 62 72 6f  tine.  The subro
22510 75 74 69 6e 65 20 67 69 76 65 6e 20 69 6e 20 74  utine given in t
22520 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  he argument is i
22530 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 69 6c 65 20  nvoked.** while 
22540 68 6f 6c 64 69 6e 67 20 61 20 73 74 61 74 69 63  holding a static
22550 20 6d 75 74 65 78 2e 20 20 54 68 69 73 20 65 6e   mutex.  This en
22560 73 75 72 65 73 20 74 68 61 74 20 6e 6f 20 6f 74  sures that no ot
22570 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 20 69 73  her.** thread is
22580 20 72 75 6e 6e 69 6e 67 20 74 68 69 73 20 73 61   running this sa
22590 6d 65 20 73 75 62 72 6f 75 74 69 6e 65 20 61 74  me subroutine at
225a0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
225b0 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
225c0 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   *sqlite3_mutex_
225d0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
225e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
225f0 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ree(sqlite3_mute
22600 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
22610 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
22620 69 74 65 33 5f 6d 75 74 65 78 2a 2c 20 69 6e 74  ite3_mutex*, int
22630 20 62 6c 6f 63 6b 46 6c 61 67 29 3b 0a 76 6f 69   blockFlag);.voi
22640 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
22650 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75  leave(sqlite3_mu
22660 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
22670 65 33 5f 6d 75 74 65 78 5f 73 65 72 69 61 6c 69  e3_mutex_seriali
22680 7a 65 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  ze(void(*)(void*
22690 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 0a 2f 2a 0a  ), void*);.../*.
226a0 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b  ** Undo the hack
226b0 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66   that converts f
226c0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79  loating point ty
226d0 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66  pes to integer f
226e0 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20  or.** builds on 
226f0 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f  processors witho
22700 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ut floating poin
22710 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69  t support..*/.#i
22720 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
22730 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
22740 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23  # undef double.#
22750 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f  endif..#ifdef __
22760 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20  cplusplus.}  /* 
22770 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65  End of the 'exte
22780 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f  rn "C"' block */
22790 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a     .#endif.#endif.