/ Hex Artifact Content
Login

Artifact c691ae04f7c064d853710a1eff4707549a54e1f8:


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 33 33 20 32 30 30 37 2f  in,v 1.233 2007/
05f0: 30 38 2f 32 31 20 31 36 3a 31 35 3a 35 36 20 64  08/21 16:15:56 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 2a 0a 2a 2a 20 50 61 73 73 69  pen..**.** Passi
1860: 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1870: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1880: 63 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61  ction that has a
1890: 6c 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63  lready been.** c
18a0: 6c 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e  losed results in
18b0: 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
18c0: 69 6f 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69  ior.  If other i
18d0: 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a  nterfaces that.*
18e0: 2a 20 72 65 66 65 72 65 6e 63 65 20 74 68 65 20  * reference the 
18f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1900: 6e 6e 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e  nnection are pen
1910: 64 69 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20  ding (either in 
1920: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65  the.** same thre
1930: 61 64 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65  ad or in differe
1940: 6e 74 20 74 68 72 65 61 64 73 29 20 77 68 65 6e  nt threads) when
1950: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1960: 20 63 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e   called,.** then
1970: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1980: 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69   undefined and i
1990: 73 20 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e  s almost certain
19a0: 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
19b0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
19c0: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b  lose(sqlite3 *);
19d0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
19e0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
19f0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
1a00: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
1a10: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
1a20: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
1a30: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
1a40: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
1a50: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
1a60: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
1a70: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
1a80: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
1a90: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
1aa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab0: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
1ac0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
1ad0: 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  face.**.** This 
1ae0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1af0: 64 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69  d to do a one-ti
1b00: 6d 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20  me evaluatation 
1b10: 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f  of zero.** or mo
1b20: 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1b30: 73 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f  s.  UTF-8 text o
1b40: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1b50: 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76  ents to.** be ev
1b60: 61 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64  aluted is passed
1b70: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e   in as the secon
1b80: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1b90: 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
1ba0: 61 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65  are prepared one
1bb0: 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73   by one using [s
1bc0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1bd0: 5d 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  ], evaluated.** 
1be0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1bf0: 74 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73  tep()], then des
1c00: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71  troyed using [sq
1c10: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1c20: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20  ]..**.** If one 
1c30: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
1c40: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1c50: 65 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a  e queries, then.
1c60: 2a 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** the callback 
1c70: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69  function specifi
1c80: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
1c90: 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e  rameter is.** in
1ca0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
1cb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71  ach row of the q
1cc0: 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68  uery result.  Th
1cd0: 69 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73  is callback.** s
1ce0: 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72  hould normally r
1cf0: 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65  eturn 0.  If the
1d00: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d10: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20  s a non-zero.** 
1d20: 76 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71  value then the q
1d30: 75 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c  uery is aborted,
1d40: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
1d50: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1d60: 2a 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e  * are skipped an
1d70: 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  d the sqlite3_ex
1d80: 65 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ec() function re
1d90: 74 75 72 6e 73 20 74 68 65 20 53 51 4c 49 54 45  turns the SQLITE
1da0: 5f 41 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ABORT..**.** Th
1db0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
1dc0: 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
1dd0: 65 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  e is an arbitrar
1de0: 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  y pointer that i
1df0: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
1e00: 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
1e10: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  ack function as 
1e20: 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
1e30: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32  ter..**.** The 2
1e40: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1e50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
1e60: 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d  ction is the num
1e70: 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e  ber of.** column
1e80: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72  s in the query r
1e90: 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20  esult.  The 3rd 
1ea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1eb0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1ec0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69  an array of stri
1ed0: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20  ngs holding the 
1ee0: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20  values for each 
1ef0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74  column.** as ext
1f00: 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71  racted using [sq
1f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1f20: 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68  t()]..** The 4th
1f30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f40: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1f50: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67   array of string
1f60: 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73  s.** obtained us
1f70: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
1f80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
1f90: 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e  holding.** the n
1fa0: 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c  ames of each col
1fb0: 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  umn..**.** The c
1fc0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fd0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76   may be NULL, ev
1fe0: 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20  en for queries. 
1ff0: 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62   A NULL.** callb
2000: 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72  ack is not an er
2010: 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65  ror.  It just me
2020: 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c  ans that no call
2030: 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  back.** will be 
2040: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  invoked..**.** I
2050: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2060: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20  s while parsing 
2070: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  or evaluating th
2080: 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f  e SQL (but.** no
2090: 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e  t while executin
20a0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20  g the callback) 
20b0: 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  then an appropri
20c0: 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  ate error.** mes
20d0: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
20e0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
20f0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2100: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
2110: 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d  .** *errmsg is m
2120: 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2130: 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54  that message.  T
2140: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2150: 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e  ion.** is respon
2160: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
2170: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  g the memory tha
2180: 74 20 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f  t holds the erro
2190: 72 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20 20 20  r.** message.   
21a0: 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  Use [sqlite3_fre
21b0: 65 28 29 5d 20 66 6f 72 20 74 68 69 73 2e 20 20  e()] for this.  
21c0: 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c  If errmsg==NULL,
21d0: 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f  .** then no erro
21e0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 65 76 65  r message is eve
21f0: 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  r written..**.**
2200: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
2210: 65 20 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f  e is is SQLITE_O
2220: 4b 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  K if there are n
2230: 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20  o errors and.** 
2240: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49  some other [SQLI
2250: 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63  TE_OK | return c
2260: 6f 64 65 5d 20 69 66 20 74 68 65 72 65 20 69 73  ode] if there is
2270: 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20   an error.  .** 
2280: 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 72  The particular r
2290: 65 74 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65  eturn value depe
22a0: 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20  nds on the type 
22b0: 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f  of error. .**.*/
22c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65  .int sqlite3_exe
22d0: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
22e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2300: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
2310: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
2320: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
2330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2340: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
2350: 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69   evaluted */.  i
2360: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
2370: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2380: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
2390: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
23a0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
23b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
23d0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
23e0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
23f0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
2400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2410: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
2420: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
2430: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2450: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
2460: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a  ORDS: SQLITE_OK.
2470: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
2480: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2490: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
24a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
24b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
24c0: 61 62 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74  above in order t
24d0: 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63  o indicates succ
24e0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
24f0: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74  **.** The result
2500: 20 63 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65   codes above are
2510: 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72   the only ones r
2520: 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
2530: 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61  e in its.** defa
2540: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
2550: 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65  n.  However, the
2560: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
2570: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
2580: 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65  )].** API can be
2590: 20 75 73 65 64 20 74 6f 20 73 65 74 20 61 20 64   used to set a d
25a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f  atabase connecto
25b0: 69 6e 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72  in to return mor
25c0: 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65  e detailed.** re
25d0: 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a  sult codes..**.*
25e0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
25f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
2600: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
2610: 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64   codes].**.*/.#d
2620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
2630: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
2640: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
2650: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
2660: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
2670: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
2680: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
2690: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
26a0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
26b0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
26c0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
26d0: 20 20 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20       2   /* NOT 
26e0: 55 53 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c  USED. Internal l
26f0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
2700: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
2710: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
2720: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
2730: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
2740: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
2750: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
2760: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
2770: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
2780: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
2790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27a0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
27b0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
27c0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
27d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27e0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
27f0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
2800: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2810: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
2820: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
2830: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
2840: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
2850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2860: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
2870: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
2880: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
2890: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
28a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
28b0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
28c0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
28d0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
28e0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
28f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
2900: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
2910: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
2920: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
2930: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
2940: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
2950: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
2960: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
2970: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
2980: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
2990: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
29a0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
29b0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
29c0: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
29d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
29e0: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
29f0: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
2a00: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
2a10: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
2a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
2a30: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
2a40: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
2a50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2a60: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
2a70: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
2a80: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
2a90: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
2aa0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
2ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2ac0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
2ad0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
2ae0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
2af0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
2b00: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
2b10: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b20: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
2b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
2b40: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
2b50: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
2b60: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
2b70: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
2b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
2b90: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
2ba0: 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76  e to contraint v
2bb0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
2bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
2bd0: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
2be0: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
2bf0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
2c00: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
2c10: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
2c20: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
2c30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c40: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
2c50: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
2c60: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
2c70: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
2c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c90: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
2ca0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
2cb0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
2cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
2cd0: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
2ce0: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
2cf0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
2d00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d10: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
2d20: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
2d30: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2d40: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
2d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2d60: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
2d70: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
2d80: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
2d90: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
2da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2db0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
2dc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
2dd0: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
2de0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
2df0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
2e00: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
2e10: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
2e20: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2e30: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
2e40: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
2e50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e60: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
2e70: 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e  t Codes.**.** In
2e80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
2e90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
2ea0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
2eb0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
2ec0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75   integer.** resu
2ed0: 6c 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62  lt codes describ
2ee0: 65 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64  ed at result-cod
2ef0: 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  es.  However, ex
2f00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
2f10: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
2f20: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
2f30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
2f40: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
2f50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
2f60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
2f70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2f80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72  problems as user
2f90: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
2fa0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
2fb0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
2fc0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
2fd0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
2fe0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
2ff0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
3000: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
3010: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
3020: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
3030: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
3040: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
3050: 74 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65  t errors.  The e
3060: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3070: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
3080: 20 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66   (or disabled) f
3090: 6f 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61  or .** each data
30a0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30b0: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  on using the [sq
30c0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
30d0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
30e0: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20  PI..** .** Some 
30f0: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
3100: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3110: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
3120: 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65  d above..** We e
3130: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
3140: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
3150: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
3160: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
3170: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
3180: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
3190: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
31a0: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
31b0: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
31c0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
31d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
31e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54  SQLite..** .** T
31f0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
3200: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
3210: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77   result code alw
3220: 61 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72  ays contains a r
3230: 65 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72  elated.** primar
3240: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73  y result code as
3250: 20 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d   a prefix.  Prim
3260: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ary result codes
3270: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
3280: 65 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74  e.** "_" charact
3290: 65 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65  er.  Extended re
32a0: 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61  sult codes conta
32b0: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
32c0: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
32d0: 2a 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61  * The numeric va
32e0: 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64  lue of an extend
32f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63  ed result code c
3300: 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  an be converted 
3310: 74 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73  to its.** corres
3320: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
3330: 72 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d  result code by m
3340: 61 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c  asking off the l
3350: 6f 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a  ower 8 bytes..**
3360: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
3370: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
3380: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
3390: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
33a0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
33b0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
33c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
33d0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
33e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
33f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
3400: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
3410: 52 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49  RT_READ    (SQLI
3420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
3430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
3440: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
3450: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
3460: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
3470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3480: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
3490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
34a0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
34b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
34c0: 52 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c  R_FSYNC     (SQL
34d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c  ITE_IOERR | (5<<
34e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
34f0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54  TE_IOERR_TRUNCAT
3500: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49  E      (SQLITE_I
3510: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
3520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3530: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
3540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3550: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
3560: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
3570: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  NLOCK        (SQ
3580: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
3590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
35a0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
35b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
35c0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a  IOERR | (9<<8)).
35d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35e0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20  OERR_DELETE     
35f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
3600: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
3610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3620: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28  _BLOCKED       (
3630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3640: 31 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  11<<8))../*.** C
3650: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
3660: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
3670: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f  rations.**.** Co
3680: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
3690: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76   following bit v
36a0: 61 6c 75 65 73 20 61 72 65 20 75 73 65 64 20 61  alues are used a
36b0: 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  s the.** third a
36c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
36d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
36e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
36f0: 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72  .** as fourth ar
3700: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f  gument to the xO
3710: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
3720: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
3730: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f  s] object..**.*/
3740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3750: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
3760: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
3770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3780: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
3790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
37a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37b0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
37c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
37d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37e0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
37f0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
3800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3810: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
3820: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
3830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3840: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
3850: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
3860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3870: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
3880: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
3890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38a0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
38b0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 33 30 30  L     0x00000300
38c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38d0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
38e0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  L     0x00000400
38f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3900: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
3910: 20 20 20 20 20 20 30 78 30 30 30 30 30 35 30 30        0x00000500
3920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3930: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
3940: 4e 41 4c 20 20 20 30 78 30 30 30 30 30 36 30 30  NAL   0x00000600
3950: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3960: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
3970: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
3980: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
3990: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
39a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
39b0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
39c0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
39d0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
39e0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
39f0: 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74  following.** bit
3a00: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
3a10: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
3a20: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
3a30: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
3a40: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
3a50: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
3a70: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
3a80: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
3a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
3aa0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
3ab0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
3ac0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
3ad0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3ae0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3af0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
3b00: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
3b10: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
3b20: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
3b30: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
3b40: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
3b50: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
3b60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
3b70: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
3b80: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
3ba0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
3bb0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
3bc0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
3bd0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
3be0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
3bf0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
3c00: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
3c10: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
3c20: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
3c30: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
3c40: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
3c50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
3c60: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
3c70: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
3c80: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
3c90: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
3ca0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
3cb0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
3cc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
3cd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
3cf0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
3d00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d10: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30  512       0x0000
3d20: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
3d30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d40: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  1K        0x0000
3d50: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
3d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3d70: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  2K        0x0000
3d80: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
3d90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3da0: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  4K        0x0000
3db0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
3dc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3dd0: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  8K        0x0000
3de0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
3df0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e00: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  16K       0x0000
3e10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
3e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e30: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  32K       0x0000
3e40: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
3e50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
3e60: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  64K       0x0000
3e70: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
3e80: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
3e90: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30  PPEND     0x0000
3ea0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
3eb0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
3ec0: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30  TIAL      0x0000
3ed0: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0400../*.** CAPI
3ee0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
3ef0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
3f00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
3f10: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3f20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
3f30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
3f40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3f50: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
3f60: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
3f70: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
3f80: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
3f90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
3fa0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
3fb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
3fc0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
3fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
3fe0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
3ff0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
4000: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
4010: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
4020: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
4030: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
4040: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
4050: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
4060: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
4070: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
4080: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
4090: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
40a0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
40b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
40c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
40d0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75  ].** object it u
40e0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
40f0: 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  n of the followi
4100: 6e 67 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ng integer value
4110: 73 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f  s as.** the seco
4120: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
4130: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
4140: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4150: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
4160: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
4170: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
4180: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
4190: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
41a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
41b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
41c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
41d0: 6c 75 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c  lushed.  The SQL
41e0: 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 52  ITE_SYNC_BARRIER
41f0: 20 66 6c 61 67 0a 2a 2a 20 6d 65 61 6e 73 20 74   flag.** means t
4200: 68 61 74 20 74 68 65 20 6e 6f 74 68 69 6e 67 20  hat the nothing 
4210: 61 63 74 75 61 6c 6c 79 20 6e 65 65 64 73 20 74  actually needs t
4220: 6f 20 62 65 20 73 79 6e 63 68 65 64 20 74 6f 20  o be synched to 
4230: 6d 61 73 73 20 73 74 6f 72 61 67 65 2c 0a 2a 2a  mass storage,.**
4240: 20 62 75 74 20 61 6c 6c 20 77 72 69 74 65 20 6f   but all write o
4250: 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  perations that o
4260: 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 65 20  ccur before the 
4270: 62 61 72 72 69 65 72 20 6d 75 73 74 20 63 6f 6d  barrier must com
4280: 70 6c 65 74 65 0a 2a 2a 20 62 65 66 6f 72 65 20  plete.** before 
4290: 61 6e 79 20 77 72 69 74 65 20 6f 70 65 72 61 74  any write operat
42a0: 69 6f 6e 73 20 74 68 61 74 20 6f 63 63 75 72 20  ions that occur 
42b0: 61 66 74 65 72 20 74 68 65 20 62 61 72 72 69 65  after the barrie
42c0: 72 20 62 65 67 69 6e 2e 0a 2a 2a 20 54 68 65 20  r begin..** The 
42d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
42e0: 41 4c 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  AL means to use 
42f0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
4300: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 54 68 65  emantics..** The
4310: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
4320: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 6f 20  L flag means to 
4330: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  use Mac OS-X sty
4340: 6c 65 20 66 75 6c 6c 73 79 6e 63 0a 2a 2a 20 69  le fullsync.** i
4350: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
4360: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
4370: 4c 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45  LITE_SYNC_BARRIE
4380: 52 20 20 20 20 20 20 20 30 78 30 30 30 30 31 0a  R       0x00001.
4390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
43a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
43b0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
43d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
43e0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
43f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4400: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a        0x00010...
4410: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4420: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
4430: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
4440: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
4450: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
4460: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
4470: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
4480: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
4490: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
44a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
44b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
44c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
44d0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
44e0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
44f0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
4500: 2a 2a 20 6f 66 20 74 68 65 69 72 20 6f 77 6e 20  ** of their own 
4510: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
4520: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
4530: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
4540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4550: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
4560: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
4570: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
4580: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
4590: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
45a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
45b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
45c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
45d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
45e0: 69 6c 65 20 7b 0a 20 20 73 74 72 75 63 74 20 73  ile {.  struct s
45f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
4600: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
4610: 20 4d 65 74 68 6f 64 73 20 61 67 61 69 6e 73 74   Methods against
4620: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 2a   the open file *
4630: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
4640: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4650: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
4660: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
4670: 2a 0a 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e 20  *.** Every open 
4680: 66 69 6c 65 20 69 6e 20 74 68 65 20 5b 73 71 6c  file in the [sql
4690: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
46a0: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
46b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
46c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
46d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62 6a  he following obj
46e0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
46f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a  t defines the.**
4700: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
4710: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
4720: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69   operations agai
4730: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
4740: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  e..**.** The fla
4750: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
4760: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
4770: 6f 66 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42  of SQLITE_SYNC_B
4780: 41 52 52 49 45 52 2c 0a 2a 2a 20 53 51 4c 49 54  ARRIER,.** SQLIT
4790: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 53  E_SYNC_NORMAL, S
47a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2e  QLITE_SYNC_FULL.
47b0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
47c0: 63 65 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ce means that.**
47d0: 20 64 61 74 61 20 69 73 20 6e 6f 74 20 6e 65 63   data is not nec
47e0: 65 73 73 61 72 69 6c 79 20 73 79 6e 63 65 64 20  essarily synced 
47f0: 74 6f 20 64 69 73 6b 20 63 6f 6d 70 6c 65 74 65  to disk complete
4800: 6c 79 2c 20 6f 6e 6c 79 20 74 68 61 74 0a 2a 2a  ly, only that.**
4810: 20 61 6c 6c 20 77 72 69 74 65 73 20 74 68 61 74   all writes that
4820: 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 74 68   occur before th
4830: 65 20 73 79 6e 63 20 63 6f 6d 70 6c 65 74 65 20  e sync complete 
4840: 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 77 72  before any.** wr
4850: 69 74 65 73 20 74 68 61 74 20 6f 63 63 75 72 20  ites that occur 
4860: 61 66 74 65 72 20 74 68 65 20 73 79 6e 63 2e 20  after the sync. 
4870: 20 54 68 65 20 73 65 63 6f 6e 64 20 66 6c 61 67   The second flag
4880: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 6f 72 6d 61   is the.** norma
4890: 6c 20 66 73 79 6e 63 28 29 2e 20 20 54 68 65 20  l fsync().  The 
48a0: 74 68 69 72 64 20 66 6c 61 67 20 69 73 20 61 20  third flag is a 
48b0: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
48c0: 79 6e 63 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ync..** The SQLI
48d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61  TE_SYNC_DATA fla
48e0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
48f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
4900: 74 20 6f 6e 6c 79 0a 2a 2a 20 74 68 65 20 64 61  t only.** the da
4910: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61  ta of the file a
4920: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
4930: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
4940: 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ced..** .** The 
4950: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
4960: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
4970: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
4980: 6f 66 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43  of.** SQLITE_LOC
4990: 4b 5f 4e 4f 4e 45 2c 20 53 51 4c 49 54 45 5f 4c  K_NONE, SQLITE_L
49a0: 4f 43 4b 5f 52 45 41 44 2c 20 53 51 4c 49 54 45  OCK_READ, SQLITE
49b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 2c 0a  _LOCK_RESERVED,.
49c0: 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ** SQLITE_LOCK_P
49d0: 45 4e 44 49 4e 47 2c 20 6f 72 20 53 51 4c 49 54  ENDING, or SQLIT
49e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
49f0: 2e 20 20 78 4c 6f 63 6b 28 29 0a 2a 2a 20 69 6e  .  xLock().** in
4a00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
4a10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
4a20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
4a30: 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52   .** The xCheckR
4a40: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
4a50: 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f  thod looks.** to
4a60: 20 73 65 65 20 69 66 20 61 6e 79 20 64 61 74 61   see if any data
4a70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
4a80: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a   either in this.
4a90: 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  ** process or in
4aa0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
4ab0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
4ac0: 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20  an RESERVED,.** 
4ad0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
4ae0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
4af0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
4b00: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
4b10: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
4b20: 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e  s and false if n
4b30: 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 78 42 72 65 61  ot..** .** xBrea
4b40: 6b 4c 6f 63 6b 28 29 20 61 74 74 65 6d 70 74 73  kLock() attempts
4b50: 20 74 6f 20 62 72 65 61 6b 20 61 20 6c 6f 63 6b   to break a lock
4b60: 20 68 65 6c 64 20 62 79 20 61 6e 6f 74 68 65 72   held by another
4b70: 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
4b80: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
4b90: 20 72 65 6d 6f 76 65 20 61 20 73 74 61 6c 65 20   remove a stale 
4ba0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 2c 20 66  dot-file lock, f
4bb0: 6f 72 20 65 78 61 6d 70 6c 65 2e 0a 2a 2a 20 49  or example..** I
4bc0: 74 20 72 65 74 75 72 6e 73 20 30 20 6f 6e 20 73  t returns 0 on s
4bd0: 75 63 63 65 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a  uccess and non-z
4be0: 65 72 6f 20 66 6f 72 20 61 20 66 61 69 6c 75 72  ero for a failur
4bf0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
4c00: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
4c10: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
4c20: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
4c30: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
4c40: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
4c50: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
4c60: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
4c70: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
4c80: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
4c90: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
4ca0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
4cb0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
4cc0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
4cd0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
4ce0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
4cf0: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
4d00: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
4d10: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
4d20: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
4d30: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4d40: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4d50: 5f 41 54 4f 4d 49 43 0a 2a 2a 20 3c 6c 69 3e 20  _ATOMIC.** <li> 
4d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4d70: 4d 49 43 35 31 32 0a 2a 2a 20 3c 6c 69 3e 20 53  MIC512.** <li> S
4d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d90: 49 43 31 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c  IC1K.** <li> SQL
4da0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4db0: 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54  2K.** <li> SQLIT
4dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
4dd0: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f  .** <li> SQLITE_
4de0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 0a 2a  IOCAP_ATOMIC8K.*
4df0: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f  * <li> SQLITE_IO
4e00: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 0a 2a 2a  CAP_ATOMIC16K.**
4e10: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43   <li> SQLITE_IOC
4e20: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 0a 2a 2a 20  AP_ATOMIC32K.** 
4e30: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e40: 50 5f 41 54 4f 4d 49 43 36 34 4b 0a 2a 2a 20 3c  P_ATOMIC64K.** <
4e50: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  li> SQLITE_IOCAP
4e60: 5f 53 41 46 45 5f 41 50 50 45 4e 44 0a 2a 2a 20  _SAFE_APPEND.** 
4e70: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41  <li> SQLITE_IOCA
4e80: 50 5f 53 45 51 55 45 4e 54 49 41 4c 0a 2a 2a 20  P_SEQUENTIAL.** 
4e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
4ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4eb0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
4ec0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
4ed0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
4ee0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
4ef0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4f00: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
4f10: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
4f20: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
4f30: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
4f40: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
4f50: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
4f60: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
4f70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
4f80: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
4f90: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
4fa0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4fb0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
4fc0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
4fd0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
4fe0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
4ff0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5000: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5010: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5020: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5030: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5040: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5050: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5060: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5070: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5080: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5090: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
50a0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
50b0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
50c0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
50d0: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
50e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
5100: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
5110: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
5120: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
5130: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
5140: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
5150: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
5160: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
5170: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
5180: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69 6e   iAmt, sqlite_in
5190: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
51a0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
51b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
51c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
51d0: 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69  , sqlite_int64 i
51e0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
51f0: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
5200: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f  3_file*, sqlite_
5210: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
5220: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
5230: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
5240: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
5250: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
5260: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f  3_file*, sqlite_
5270: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
5280: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
5290: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
52a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
52b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
52c0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
52d0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
52e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
52f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 72  e*);.  int (*xBr
5300: 65 61 6b 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  eakLock)(sqlite3
5310: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
5320: 2a 78 4c 6f 63 6b 53 74 61 74 65 29 28 73 71 6c  *xLockState)(sql
5330: 69 74 65 33 5f 66 69 6c 65 20 2a 29 3b 0a 20 20  ite3_file *);.  
5340: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
5350: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
5360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
5370: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5380: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
5390: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
53a0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
53b0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
53c0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
53d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
53e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
53f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
5400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
5410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
5420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
5430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
5440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
5450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
5460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
5470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
5480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
5490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
54a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
54b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
54c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
54d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
54e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
54f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
5500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
5510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
5520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
5530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
5550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
5560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
5580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
5590: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
55a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
55b0: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
55c0: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  * SQLite core an
55d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
55e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
55f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
5600: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
5610: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
5620: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
5630: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
5640: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  ** The iVersion 
5650: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
5660: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
5670: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72  larger for futur
5680: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
5690: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
56a0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
56b0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
56c0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
56d0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
56e0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
56f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
5700: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
5710: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5720: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
5730: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63  e3_file.** struc
5740: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
5750: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
5760: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
5770: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
5780: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
5790: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  s VFS..**.** The
57a0: 20 6e 52 65 66 20 66 69 65 6c 64 20 69 73 20 69   nRef field is i
57b0: 6e 63 72 65 6d 65 6e 74 65 64 20 61 6e 64 20 64  ncremented and d
57c0: 65 63 72 65 6d 65 6e 74 65 64 20 62 79 20 53 51  ecremented by SQ
57d0: 4c 69 74 65 20 74 6f 20 6b 65 65 70 0a 2a 2a 20  Lite to keep.** 
57e0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
57f0: 62 65 72 20 6f 66 20 75 73 65 72 73 20 6f 66 20  ber of users of 
5800: 74 68 65 20 56 46 53 2e 20 20 54 68 69 73 20 66  the VFS.  This f
5810: 69 65 6c 64 20 61 6e 64 0a 2a 2a 20 76 66 73 4d  ield and.** vfsM
5820: 75 74 65 78 2c 20 70 4e 65 78 74 2c 20 61 6e 64  utex, pNext, and
5830: 20 70 50 72 65 76 20 61 72 65 20 74 68 65 20 6f   pPrev are the o
5840: 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68  nly fields in th
5850: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a  e sqlite3_vfs .*
5860: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
5870: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
5880: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
5890: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
58a0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
58b0: 74 68 65 73 65 20 66 69 65 6c 64 73 20 77 68 69  these fields whi
58c0: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
58d0: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
58e0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
58f0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
5900: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
5910: 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 73   fields of the s
5920: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
5930: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
5940: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
5950: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 0a 2a 2a  gistered..** .**
5960: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
5970: 2e 76 66 73 4d 75 74 65 78 20 69 73 20 61 20 6d  .vfsMutex is a m
5980: 75 74 65 78 20 75 73 65 64 20 62 79 20 74 68 65  utex used by the
5990: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a   OS interface..*
59a0: 2a 20 49 74 20 73 68 6f 75 6c 64 20 69 6e 69 74  * It should init
59b0: 69 61 6c 6c 79 20 62 65 20 4e 55 4c 4c 2e 20 20  ially be NULL.  
59c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 69 74  SQLite will init
59d0: 69 61 6c 69 7a 65 20 74 68 69 73 20 66 69 65 6c  ialize this fiel
59e0: 64 0a 2a 2a 20 75 73 69 6e 67 20 73 71 6c 69 74  d.** using sqlit
59f0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
5a00: 20 75 70 6f 6e 20 66 69 72 73 74 20 75 73 65 20   upon first use 
5a10: 6f 66 20 74 68 65 20 61 64 61 70 74 6f 72 0a 2a  of the adaptor.*
5a20: 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6f 70 65  * by sqlite3_ope
5a30: 6e 5f 76 32 28 29 20 61 6e 64 20 77 69 6c 6c 20  n_v2() and will 
5a40: 64 65 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d  deallocate the m
5a50: 75 74 65 78 20 77 68 65 6e 20 74 68 65 0a 2a 2a  utex when the.**
5a60: 20 6c 61 73 74 20 75 73 65 72 20 63 6c 6f 73 65   last user close
5a70: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
5a80: 64 73 2c 20 76 66 73 4d 75 74 65 78 20 77 69 6c  ds, vfsMutex wil
5a90: 6c 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  l be allocated.*
5aa0: 2a 20 77 68 65 6e 20 6e 52 65 66 20 74 72 61 6e  * when nRef tran
5ab0: 73 69 74 69 6f 6e 73 20 66 72 6f 6d 20 30 20 74  sitions from 0 t
5ac0: 6f 20 31 20 61 6e 64 20 77 69 6c 6c 20 62 65 20  o 1 and will be 
5ad0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
5ae0: 0a 2a 2a 20 6e 52 65 66 20 74 72 61 6e 73 69 74  .** nRef transit
5af0: 69 6f 6e 73 20 66 72 6f 6d 20 31 20 74 6f 20 30  ions from 1 to 0
5b00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
5b10: 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61  ed vfs modules a
5b20: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
5b30: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
5b40: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
5b50: 61 6e 64 20 70 50 72 65 76 20 70 6f 69 6e 74 65  and pPrev pointe
5b60: 72 73 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  rs.  The [sqlite
5b70: 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28 29  3_register_vfs()
5b80: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
5b90: 33 5f 75 6e 72 65 67 69 73 74 65 72 5f 76 66 73  3_unregister_vfs
5ba0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
5bb0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
5bc0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
5bd0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
5be0: 71 6c 69 74 65 33 5f 61 63 71 75 69 72 65 5f 76  qlite3_acquire_v
5bf0: 66 73 28 29 5d 20 73 65 61 72 63 68 65 73 20 74  fs()] searches t
5c00: 68 65 0a 2a 2a 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  he.** list..**.*
5c10: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
5c20: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
5c30: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
5c40: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
5c50: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
5c60: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
5c70: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51  odules..**.** SQ
5c80: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
5c90: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
5ca0: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
5cb0: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
5cc0: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
5cd0: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
5ce0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
5cf0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
5d00: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
5d10: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
5d20: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
5d30: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
5d40: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 73 71  lled.  So the sq
5d50: 6c 69 74 65 33 5f 66 69 6c 65 20 63 61 6e 20 73  lite3_file can s
5d60: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
5d70: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
5d80: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
5d90: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
5da0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
5db0: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  reason..**.** Th
5dc0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
5dd0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61   to xOpen() is a
5de0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61   copy of the fla
5df0: 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  gs argument.** t
5e00: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
5e10: 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65 33  2().  If sqlite3
5e20: 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
5e30: 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69  e3_open16().** i
5e40: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
5e50: 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 50 45  gs is SQLITE_OPE
5e60: 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20 53 51  N_READWRITE | SQ
5e70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5e80: 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  ..** If xOpen() 
5e90: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
5ea0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
5eb0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
5ec0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c  o.** include SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5ee0: 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  Y.  Other bits i
5ef0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
5f00: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a   be.** set..** .
5f10: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
5f20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
5f30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
5f40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
5f50: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
5f60: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
5f70: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
5f80: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
5f90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
5fa0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
5fb0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
5fc0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
5fd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
5fe0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
5ff0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
6000: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
6010: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
6020: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
6030: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6050: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
6060: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
6070: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
6080: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
6090: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
60a0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
60b0: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  s the way it dea
60c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
60d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
60e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
60f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
6100: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
6110: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
6120: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ck, might make.*
6130: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
6140: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
6150: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
6160: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72   this journal ar
6170: 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f  e.** also a no-o
6180: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  p.  Any attempt 
6190: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
61a0: 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  nal return SQLIT
61b0: 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74  E_IOERR..** Or t
61c0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
61d0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
61e0: 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65  e the a database
61f0: 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65   file will.** be
6200: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
6210: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
6220: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
6230: 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a   random order.**
6240: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
6250: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
6260: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a  cordingly..** .*
6270: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
6280: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
6290: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
62a0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a  gs to the xOpen.
62b0: 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a  ** method:.** .*
62c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
62d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
62e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
62f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
6300: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
6310: 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b  ul>.** .** The [
6320: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
6330: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
6340: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
6350: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
6360: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
6370: 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c  losed.  This wil
6380: 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20  l always be set 
6390: 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74  for TEMP .** dat
63a0: 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e  abases and journ
63b0: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
63c0: 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a  ournals.  The .*
63d0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  * [SQLITE_OPEN_E
63e0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
63f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
6400: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
6410: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
6420: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
6430: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
6440: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
6450: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
6460: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
6470: 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33   .** The sqlite3
6480: 5f 66 69 6c 65 20 73 74 72 75 63 74 75 72 65 20  _file structure 
6490: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
64a0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ird argument to.
64b0: 2a 2a 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f  ** xOpen is allo
64c0: 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 6c  cated by the cal
64d0: 6c 65 72 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74  ler.  xOpen just
64e0: 20 66 69 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54   fills it in.  T
64f0: 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c  he.** caller all
6500: 6f 63 61 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d  ocates a minimum
6510: 20 6f 66 20 73 7a 4f 73 46 69 6c 65 20 62 79 74   of szOsFile byt
6520: 65 73 20 66 6f 72 20 74 68 65 20 73 71 6c 69 74  es for the sqlit
6530: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63  e3_file.** struc
6540: 74 75 72 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  ture..** .** The
6550: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6560: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
6570: 20 62 65 20 30 20 28 74 6f 20 74 65 73 74 20 66   be 0 (to test f
6580: 6f 72 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61  or the.** exista
6590: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f  nce of a file) o
65a0: 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  r SQLITE_ACCESS_
65b0: 52 45 41 44 57 52 49 54 45 20 74 6f 20 74 65 73  READWRITE to tes
65c0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
65d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
65e0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
65f0: 6f 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  or SQLITE_ACCESS
6600: 5f 52 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20  _READONLY.** to 
6610: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61  test to see if a
6620: 20 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e   file is read-on
6630: 6c 79 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61  ly.  The file ca
6640: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63  n be a .** direc
6650: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c  tory..** .** SQL
6660: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
6670: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
6680: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
6690: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
66a0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
66b0: 72 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61  r xGetTempName a
66c0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
66d0: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
66e0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
66f0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
6700: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
6710: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
6720: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
6730: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
6740: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
6750: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
6760: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
6770: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
6780: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
6790: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
67a0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
67b0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
67c0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
67d0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
67e0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
67f0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
6800: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
6810: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
6820: 61 6e 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61  andomness genera
6830: 74 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c  ted.  The.** xSl
6840: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
6850: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  se the calling t
6860: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
6870: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
6880: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
6890: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
68a0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
68b0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
68c0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
68d0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
68e0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
68f0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a  and.** time..*/.
6900: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6910: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
6920: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
6930: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
6940: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
6950: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
6960: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
6970: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
6980: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
6990: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
69a0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
69b0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
69c0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
69d0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
69e0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
69f0: 74 68 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  th */.  int nRef
6a00: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
6a10: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
6a20: 66 65 72 65 6e 63 65 73 20 74 6f 20 74 68 69 73  ferences to this
6a30: 20 73 74 72 75 63 74 75 72 65 20 2a 2f 0a 20 20   structure */.  
6a40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 76  sqlite3_mutex *v
6a50: 66 73 4d 75 74 65 78 3b 20 2f 2a 20 41 20 6d 75  fsMutex; /* A mu
6a60: 74 65 78 20 66 6f 72 20 74 68 69 73 20 56 46 53  tex for this VFS
6a70: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
6a80: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
6a90: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
6aa0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
6ab0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
6ac0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
6ad0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
6ae0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
6af0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
6b00: 20 20 20 20 20 20 2f 2a 20 41 70 70 6c 69 63 61        /* Applica
6b10: 74 69 6f 6e 20 63 6f 6e 74 65 78 74 20 2a 2f 0a  tion context */.
6b20: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 76    int (*xOpen)(v
6b30: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63  oid *pAppData, c
6b40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6b50: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
6b60: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
6b70: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
6b80: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
6b90: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 76 6f 69  t (*xDelete)(voi
6ba0: 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e  d *pAppData, con
6bb0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
6bc0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
6bd0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 76  int (*xAccess)(v
6be0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63  oid *pAppData, c
6bf0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
6c00: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
6c10: 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 4e 61  int (*xGetTempNa
6c20: 6d 65 29 28 76 6f 69 64 20 2a 70 41 70 70 44 61  me)(void *pAppDa
6c30: 74 61 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ta, char *zOut);
6c40: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
6c50: 74 68 6e 61 6d 65 29 28 76 6f 69 64 20 2a 70 41  thname)(void *pA
6c60: 70 70 44 61 74 61 2c 20 63 6f 6e 73 74 20 63 68  ppData, const ch
6c70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72 20  ar *zName, char 
6c80: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
6c90: 28 2a 78 44 6c 4f 70 65 6e 29 28 76 6f 69 64 20  (*xDlOpen)(void 
6ca0: 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e 73 74  *pAppData, const
6cb0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
6cc0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
6cd0: 72 72 6f 72 29 28 76 6f 69 64 20 2a 70 41 70 70  rror)(void *pApp
6ce0: 44 61 74 61 2c 20 69 6e 74 20 6e 42 79 74 65 2c  Data, int nByte,
6cf0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
6d00: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
6d10: 6d 29 28 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  m)(void*, const 
6d20: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
6d30: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
6d40: 65 29 28 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  e)(void*);.  int
6d50: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
6d60: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20  void *pAppData, 
6d70: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
6d80: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
6d90: 78 53 6c 65 65 70 29 28 76 6f 69 64 20 2a 70 41  xSleep)(void *pA
6da0: 70 70 44 61 74 61 2c 20 69 6e 74 20 6d 69 63 72  ppData, int micr
6db0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
6dc0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
6dd0: 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c  (void *pAppData,
6de0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20   double*);.  /* 
6df0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
6e00: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
6e10: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
6e20: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
6e30: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
6e40: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
6e50: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f  this happens. */
6e60: 0a 7d 3b 0a 0a 23 64 65 66 69 6e 65 20 53 51 4c  .};..#define SQL
6e70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
6e80: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
6e90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
6ea0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
6eb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
6ec0: 45 41 44 4f 4e 4c 59 20 20 32 0a 0a 2f 2a 0a 2a  EADONLY  2../*.*
6ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
6ee0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
6ef0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
6f00: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  des.**.** This r
6f10: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
6f20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
6f30: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
6f40: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
6f50: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
6f60: 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 66  ature..** By def
6f70: 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 49  ault, SQLite API
6f80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
6f90: 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 20   one of only 26 
6fa0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
6fb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
6fc0: 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 74  odes].  When ext
6fd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
6fe0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
6ff0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
7000: 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 65  e, the repetoire
7010: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73   of result codes
7020: 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20   can be.** much 
7030: 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28  larger and can (
7040: 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69  hopefully) provi
7050: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
7060: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
7070: 61 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 20  about the cause 
7080: 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  of an error..**.
7090: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
70a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c  gument is a bool
70b0: 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 74  ean value that t
70c0: 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 65  urns extended re
70d0: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e  sult.** codes on
70e0: 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 6e   and off.  Exten
70f0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
7100: 20 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61   are off by defa
7110: 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77  ult for.** backw
7120: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
7130: 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65  ty with older ve
7140: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
7150: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
7160: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
7170: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
7180: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
7190: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
71a0: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
71b0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79  **.** Each entry
71c0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
71d0: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
71e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
71f0: 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 61  nteger key.** ca
7200: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22  lled the "rowid"
7210: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61  . The rowid is a
7220: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 20  lways available 
7230: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
7240: 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  .** column named
7250: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
7260: 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 65  _ROWID_.  If the
7270: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
7280: 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 49  umn of.** type I
7290: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
72a0: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
72b0: 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 61  umn is another a
72c0: 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 0a  n alias for the.
72d0: 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  ** rowid..**.** 
72e0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
72f0: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
7300: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
7310: 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a  t INSERT into.**
7320: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
7330: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
7340: 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e  connection given
7350: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a   in the first .*
7360: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
7370: 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 20  no inserts have 
7380: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
7390: 20 74 68 69 73 20 64 61 74 61 62 61 73 65 0a 2a   this database.*
73a0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  * connection, ze
73b0: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
73c0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45  **.** If an INSE
73d0: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  RT occurs within
73e0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
73f0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
7400: 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f  e.** inserted ro
7410: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
7420: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
7430: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
7440: 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  gger.** is runni
7450: 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68  ng.  But once th
7460: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
7470: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
7480: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74  returned.** by t
7490: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
74a0: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
74b0: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
74c0: 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69  efore the.** tri
74d0: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
74e0: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
74f0: 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69  ead does a new i
7500: 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d  nsert on the sam
7510: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
7520: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74  ction.** while t
7530: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
7540: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
7550: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
7560: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
7570: 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
7580: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
7590: 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
75a0: 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ined..*/.sqlite3
75b0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
75c0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
75d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
75e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
75f0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
7600: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
7610: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
7620: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
7630: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
7640: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
7650: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72 20   changed.** (or 
7660: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
7670: 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73 74  ted) by the most
7680: 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61 74   recent SQL stat
7690: 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ement.  Only.** 
76a0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
76b0: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
76c0: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
76d0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a  T, UPDATE, or.**
76e0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
76f0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
7700: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
7710: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
7720: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
7730: 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74 68  counted.  Use th
7740: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
7750: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
7760: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  tion.** to find 
7770: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
7780: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c   of changes incl
7790: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
77a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
77b0: 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20 74  ..**.** Within t
77c0: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
77d0: 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65  gger, the sqlite
77e0: 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
77f0: 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20  rface can be.** 
7800: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
7810: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
7820: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
7830: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
7840: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
7850: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
7860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
7870: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
7880: 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
7890: 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73 20  .** All changes 
78a0: 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65  are counted, eve
78b0: 6e 20 69 66 20 74 68 65 79 20 77 65 72 65 20 6c  n if they were l
78c0: 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61  ater undone by a
78d0: 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20  .** ROLLBACK or 
78e0: 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c 20  ABORT.  Except, 
78f0: 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74  changes associat
7900: 65 64 20 77 69 74 68 20 63 72 65 61 74 69 6e 67  ed with creating
7910: 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67   and.** dropping
7920: 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
7930: 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  counted..**.** I
7940: 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  f a callback inv
7950: 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  okes [sqlite3_ex
7960: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
7970: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
7980: 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 74  ively,.** then t
7990: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  he changes in th
79a0: 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69  e inner, recursi
79b0: 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e  ve call are coun
79c0: 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a 20  ted together.** 
79d0: 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65 73  with the changes
79e0: 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61   in the outer ca
79f0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ll..**.** SQLite
7a00: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
7a10: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
7a20: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
7a30: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
7a40: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
7a50: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
7a60: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
7a70: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
7a80: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
7a90: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
7aa0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
7ab0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
7ac0: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
7ad0: 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70  se of.** this op
7ae0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
7af0: 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72  change count for
7b00: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
7b10: 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ble" will be.** 
7b20: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20  zero regardless 
7b30: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
7b40: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
7b50: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69  ere originally i
7b60: 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20  n the.** table. 
7b70: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
7b80: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
7b90: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
7ba0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
7bb0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
7bc0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
7bd0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ad..**.** If ano
7be0: 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65  ther thread make
7bf0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
7c00: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
7c10: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
7c20: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
7c30: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
7c40: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
7c50: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
7c60: 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
7c70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
7c80: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
7c90: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
7ca0: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
7cb0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
7cc0: 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ed.***.** This f
7cd0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
7ce0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
7cf0: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
7d00: 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f   have been.** mo
7d10: 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54  dified by INSERT
7d20: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
7d30: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
7d40: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
7d50: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f   handle.** was o
7d60: 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c  pened. This incl
7d70: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53  udes UPDATE, INS
7d80: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73  ERT and DELETE s
7d90: 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74  tatements execut
7da0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
7db0: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
7dc0: 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61  s. All changes a
7dd0: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
7de0: 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61  on as the.** sta
7df0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
7e00: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
7e10: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
7e20: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
7e30: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
7e40: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
7e50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
7e60: 61 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alise()])..**.**
7e70: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
7e80: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d  qlite3_change()]
7e90: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7ea0: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
7eb0: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
7ec0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
7ed0: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
7ee0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
7ef0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
7f00: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
7f10: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
7f20: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
7f30: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
7f40: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
7f50: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
7f60: 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e   form the table.
7f70: 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a  )  Because of.**
7f80: 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
7f90: 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63  on, the change c
7fa0: 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45  ount for "DELETE
7fb0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c   FROM table" wil
7fc0: 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67  l be.** zero reg
7fd0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
7fe0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
7ff0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
8000: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a  inally in the.**
8010: 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61   table. To get a
8020: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
8030: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
8040: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
8050: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
8060: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
8070: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
8080: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
8090: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
80a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
80b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
80c0: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20  n.** while this 
80d0: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
80e0: 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ng then the retu
80f0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
8100: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75   routine.** is u
8110: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
8120: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
8130: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
8140: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8150: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
8160: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
8170: 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  y.**.** This fun
8180: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
8190: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
81a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
81b0: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
81c0: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
81d0: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
81e0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
81f0: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
8200: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
8210: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
8220: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
8230: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
8240: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
8250: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
8260: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
8270: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
8280: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
8290: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
82a0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
82b0: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
82c0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
82d0: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
82e0: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
82f0: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
8300: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
8310: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
8320: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
8330: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
8340: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
8350: 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69  ection that.** i
8360: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
8370: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
8380: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8390: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
83a0: 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72 61 74  * The SQL operat
83b0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
83c0: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
83d0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
83e0: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e  RRUPT]..** If an
83f0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f 70 65   interrupted ope
8400: 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20 75 70  ration was an up
8410: 64 61 74 65 20 74 68 61 74 20 69 73 20 69 6e 73  date that is ins
8420: 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  ide an.** explic
8430: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
8440: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
8450: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c  transaction will
8460: 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61   be rolled.** ba
8470: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
8480: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
8490: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
84a0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
84b0: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
84c0: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
84d0: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
84e0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  e.**.** These fu
84f0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 74  nctions return t
8500: 72 75 65 20 69 66 20 74 68 65 20 67 69 76 65 6e  rue if the given
8510: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63 6f   input string co
8520: 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f  mprises.** one o
8530: 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20  r more complete 
8540: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
8550: 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  For the sqlite3_
8560: 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c 6c 2c  complete() call,
8570: 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65  .** the paramete
8580: 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75 6c 2d  r must be a nul-
8590: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
85a0: 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20   string. For.** 
85b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
85c0: 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65 72 6d  16(), a nul-term
85d0: 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20 62  inated machine b
85e0: 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31 36  yte order UTF-16
85f0: 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65   string.** is re
8600: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
8610: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
8620: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d   useful for comm
8630: 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
8640: 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
8650: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
8660: 65 6e 74 65 72 65 64 20 74 65 78 74 20 66 6f 72  entered text for
8670: 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ms one or more c
8680: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
8690: 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69 66 20  ements or.** if 
86a0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
86b0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
86c0: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 73 74  e sending the st
86d0: 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a  atements into.**
86e0: 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
86f0: 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72 69 74  ing. The algorit
8700: 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20 49  hm is simple.  I
8710: 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74 20 74  f the .** last t
8720: 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61 6e 20  oken other than 
8730: 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d 6d 65  spaces and comme
8740: 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  nts is a semicol
8750: 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 20  on, then return 
8760: 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74 75 61  .** true.  Actua
8770: 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72 69 74  lly, the algorit
8780: 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65 20 6d  hm is a little m
8790: 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
87a0: 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69 6e 20  than that.** in 
87b0: 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20 77 69  order to deal wi
87c0: 74 68 20 74 72 69 67 67 65 72 73 2c 20 62 75 74  th triggers, but
87d0: 20 74 68 65 20 62 61 73 69 63 20 69 64 65 61 20   the basic idea 
87e0: 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20 74 68  is the same:  th
87f0: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  e.** statement i
8800: 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20 75  s not complete u
8810: 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20 69 6e  nless it ends in
8820: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f   a semicolon..*/
8830: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
8840: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
8850: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
8860: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
8870: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
8880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8890: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
88a0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
88b0: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
88c0: 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  rs.**.** This ro
88d0: 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73  utine identifies
88e0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
88f0: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
8900: 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
8910: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70  enever an attemp
8920: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
8930: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
8940: 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74  le .** that anot
8950: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
8960: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
8970: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
8980: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
8990: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
89a0: 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d  BUSY].** (or som
89b0: 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45 5f 49  etimes [SQLITE_I
89c0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a  OERR_BLOCKED]).*
89d0: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
89e0: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
89f0: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
8a00: 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  lock..** If the 
8a10: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
8a20: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
8a30: 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  the.** callback 
8a40: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
8a50: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
8a60: 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73  ts.  The.** firs
8a70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
8a80: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
8a90: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
8aa0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
8ab0: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
8ac0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
8ad0: 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65  routine.  The se
8ae0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
8af0: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
8b00: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
8b10: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
8b20: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
8b30: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
8b40: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
8b50: 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68 65 0a  g event. If the.
8b60: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
8b70: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
8b80: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
8b90: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
8ba0: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
8bc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
8bd0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
8be0: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
8bf0: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
8c00: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
8c10: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
8c20: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20 69 73  other attempt is
8c30: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
8c40: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 6f  e.** database fo
8c50: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
8c60: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
8c70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
8c80: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
8c90: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
8ca0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a  uarantee that.**
8cb0: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
8cc0: 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69  ked when there i
8cd0: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
8ce0: 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20  n..** If SQLite 
8cf0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
8d00: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
8d10: 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  y handler could 
8d20: 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64  result in.** a d
8d30: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
8d40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
8d50: 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 0a 2a  BUSY] instead..*
8d60: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
8d70: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
8d80: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
8d90: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
8da0: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
8db0: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
8dc0: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
8dd0: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
8de0: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
8df0: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
8e00: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
8e10: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
8e20: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
8e30: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
8e40: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
8e50: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
8e60: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
8e70: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
8e80: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
8e90: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
8ea0: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
8eb0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
8ec0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
8ed0: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
8ee0: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
8ef0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
8f00: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
8f10: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
8f20: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
8f30: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
8f40: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
8f50: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
8f60: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
8f70: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
8f80: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
8f90: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
8fa0: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
8fb0: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
8fc0: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
8fd0: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
8fe0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
8ff0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
9000: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  LL..**.** The [S
9010: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
9020: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
9030: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
9040: 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a  BLOCKED] when.**
9050: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
9060: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
9070: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
9080: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
9090: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
90a0: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
90b0: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
90c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
90d0: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
90e0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
90f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9100: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
9110: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
9120: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
9130: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
9140: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
9150: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
9160: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9170: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
9180: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
9190: 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73  aders.  If it is
91a0: 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
91b0: 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
91c0: 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
91d0: 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
91e0: 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
91f0: 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
9200: 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
9210: 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
9220: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
9230: 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
9240: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
9250: 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
9260: 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
9270: 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73  _BLOCKED].  This
9280: 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
9290: 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
92a0: 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
92b0: 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
92c0: 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a 2a 2a  nges. See the.**
92d0: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
92e0: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
92f0: 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
9300: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
9310: 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
9320: 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
9330: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
9340: 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
9350: 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
9360: 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
9370: 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a  mportant..**..**
9380: 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e   Sqlite is re-en
9390: 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75  trant, so the bu
93a0: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73  sy handler may s
93b0: 74 61 72 74 20 61 20 6e 65 77 20 71 75 65 72 79  tart a new query
93c0: 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74  . .** (It is not
93d0: 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f 6e   clear why anyon
93e0: 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77 61  e would every wa
93f0: 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20 62  nt to do this, b
9400: 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f  ut it.** is allo
9410: 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29  wed, in theory.)
9420: 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68    But the busy h
9430: 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63  andler may not c
9440: 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  lose the.** data
9450: 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74  base.  Closing t
9460: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
9470: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
9480: 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20  will delete .** 
9490: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
94a0: 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74  out from under t
94b0: 68 65 20 65 78 65 63 75 74 69 6e 67 20 71 75 65  he executing que
94c0: 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20  ry and will .** 
94d0: 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20  probably result 
94e0: 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
94f0: 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
9500: 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e 0a   runtime error..
9510: 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
9520: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
9530: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
9540: 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64  fined for each d
9550: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9560: 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20  ction.  Setting 
9570: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
9580: 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72  er clears any pr
9590: 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e  evious one..** N
95a0: 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
95b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
95c0: 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61  imeout()] will a
95d0: 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
95e0: 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
95f0: 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  dler..**.** When
9600: 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b 73   operating in [s
9610: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
9620: 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61  ared_cache | sha
9630: 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
9640: 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c  .** only a singl
9650: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
9660: 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66 6f  an be defined fo
9670: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
9680: 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74  file..** So if t
9690: 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  wo database conn
96a0: 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61 20  ections share a 
96b0: 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74 68  single cache, th
96c0: 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74  en changing.** t
96d0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
96e0: 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f  on one connectio
96f0: 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e  n will also chan
9700: 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ge the busy.** h
9710: 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f 74  andler in the ot
9720: 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  her connection. 
9730: 20 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   The busy handle
9740: 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  r is invoked.** 
9750: 69 6e 20 74 68 65 20 74 68 72 65 61 64 20 74 68  in the thread th
9760: 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20 77  at was running w
9770: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 42  hen the SQLITE_B
9780: 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a 2f 0a  USY was hit..*/.
9790: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
97a0: 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
97b0: 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
97c0: 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
97d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
97e0: 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
97f0: 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  t.**.** This rou
9800: 74 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79  tine sets a busy
9810: 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c   handler that sl
9820: 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65  eeps for a while
9830: 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65   when a.** table
9840: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65   is locked.  The
9850: 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c   handler will sl
9860: 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
9870: 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20  es until .** at 
9880: 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
9890: 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
98a0: 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f  ing have been do
98b0: 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d  ne.  After.** "m
98c0: 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
98d0: 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65  of sleeping, the
98e0: 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
98f0: 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73   0 which.** caus
9900: 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
9910: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53  ()] to return [S
9920: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
9930: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9940: 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
9950: 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
9960: 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
9970: 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
9980: 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
9990: 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
99a0: 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
99b0: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
99c0: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
99d0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
99e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
99f0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9a00: 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ion.  If another
9a10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61   busy handler wa
9a20: 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28  s defined  .** (
9a30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
9a40: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
9a50: 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
9a60: 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
9a70: 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
9a80: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
9a90: 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ared..*/.int sql
9aa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
9ab0: 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
9ac0: 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
9ad0: 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
9ae0: 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
9af0: 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
9b00: 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72  *.** This next r
9b10: 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e 76  outine is a conv
9b20: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
9b30: 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33 5f  around [sqlite3_
9b40: 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74  exec()]..** Inst
9b50: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
9b60: 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20  a user-supplied 
9b70: 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63  callback for eac
9b80: 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20  h row of the.** 
9b90: 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75  result, this rou
9ba0: 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65  tine remembers e
9bb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ach row of the r
9bc0: 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a  esult in memory.
9bd0: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
9be0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9bf0: 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e  ()], then return
9c00: 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73  s all of the res
9c10: 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  ult after the.**
9c20: 20 71 75 65 72 79 20 68 61 73 20 66 69 6e 69 73   query has finis
9c30: 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61  hed. .**.** As a
9c40: 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f  n example, suppo
9c50: 73 65 20 74 68 65 20 71 75 65 72 79 20 72 65 73  se the query res
9c60: 75 6c 74 20 77 68 65 72 65 20 74 68 69 73 20 74  ult where this t
9c70: 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  able:.**.** <pre
9c80: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
9c90: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
9ca0: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
9cb0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
9cc0: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
9cd0: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
9ce0: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
9cf0: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
9d00: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
9d10: 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
9d20: 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75   If the 3rd argu
9d30: 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73  ment were &azRes
9d40: 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74  ult then after t
9d50: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
9d60: 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20  rns.** azResult 
9d70: 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65  will contain the
9d80: 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a   following data:
9d90: 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
9da0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9db0: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
9dc0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9dd0: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
9de0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 32        azResult[2
9df0: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
9e00: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b         azResult[
9e10: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
9e20: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 34 5d       azResult[4]
9e30: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
9e40: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 35 5d 20      azResult[5] 
9e50: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
9e60: 20 20 61 7a 52 65 73 75 6c 74 5b 36 5d 20 3d 20    azResult[6] = 
9e70: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
9e80: 20 20 20 61 7a 52 65 73 75 6c 74 5b 37 5d 20 3d     azResult[7] =
9e90: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
9ea0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68  .**.** Notice th
9eb0: 61 74 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  at there is an e
9ec0: 78 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61  xtra row of data
9ed0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9ee0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72  column.** header
9ef0: 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f  s.  But the *nro
9f00: 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  w return value i
9f10: 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f  s still 3.  *nco
9f20: 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74  lumn is.** set t
9f30: 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c  o 2.  In general
9f40: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  , the number of 
9f50: 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20  values inserted 
9f60: 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a  into azResult.**
9f70: 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77   will be ((*nrow
9f80: 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e  ) + 1)*(*ncolumn
9f90: 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  )..**.** After t
9fa0: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
9fb0: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
9fc0: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
9fd0: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  t, it should .**
9fe0: 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
9ff0: 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f   data pointer to
a000: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
a010: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
a020: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
a030: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
a040: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65  s malloc-ed.  Be
a050: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
a060: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
a070: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
a080: 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  ens, the calling
a090: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
a0a0: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a  ot try to call .
a0b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
a0c0: 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
a0d0: 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  nly [sqlite3_fre
a0e0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
a0f0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a  le to release .*
a100: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  * the memory pro
a110: 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
a120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
a130: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
a140: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
a150: 73 61 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71  same as from [sq
a160: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a  lite3_exec()]..*
a170: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
a180: 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
a190: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
a1a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
a1b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
a1c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
a1d0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
a1e0: 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61  xecuted */.  cha
a1f0: 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20  r ***resultp,   
a200: 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72      /* Result wr
a210: 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20  itten to a char 
a220: 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73 20 70  *[]  that this p
a230: 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e  oints to */.  in
a240: 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20  t *nrow,        
a250: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
a260: 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
a270: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
a280: 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20  int *ncolumn,   
a290: 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
a2a0: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
a2b0: 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
a2c0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
a2d0: 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45  sg          /* E
a2e0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
a2f0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
a300: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
a310: 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
a320: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
a330: 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
a340: 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
a350: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
a360: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
a370: 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20  e workalikes of 
a380: 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
a390: 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
a3a0: 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
a3b0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
a3c0: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
a3d0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
a3e0: 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
a3f0: 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
a400: 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
a410: 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
a420: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a430: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a440: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
a450: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
a460: 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
a470: 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
a480: 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
a490: 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f  te3_free()].  Bo
a4a0: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
a4b0: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
a4c0: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
a4d0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
a4e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
a4f0: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
a500: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
a510: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
a520: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
a530: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
a540: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
a550: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
a560: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
a570: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
a580: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
a590: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
a5a0: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
a5b0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
a5c0: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
a5d0: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
a5e0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
a5f0: 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74  rameter.  Note t
a600: 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
a610: 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
a620: 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
a630: 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
a640: 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
a650: 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
a660: 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
a670: 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
a680: 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
a690: 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
a6a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
a6b0: 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
a6c0: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
a6d0: 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
a6e0: 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
a6f0: 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
a700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
a710: 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
a720: 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
a730: 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
a740: 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
a750: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
a760: 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
a770: 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
a780: 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
a790: 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
a7a0: 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
a7b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a7c0: 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
a7d0: 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
a7e0: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
a7f0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
a800: 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
a810: 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
a820: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
a830: 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
a840: 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
a850: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
a860: 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
a870: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
a880: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
a890: 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
a8a0: 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
a8b0: 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
a8c0: 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
a8d0: 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
a8e0: 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
a8f0: 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
a900: 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
a910: 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
a920: 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
a930: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
a940: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a950: 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
a960: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
a970: 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
a980: 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
a990: 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
a9a0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
a9b0: 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
a9c0: 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66  e usual printf f
a9d0: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
a9e0: 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
a9f0: 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
aa00: 69 73 20 61 72 65 20 22 25 71 22 20 61 6e 64 20  is are "%q" and 
aa10: 22 25 51 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%Q" options..**
aa20: 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
aa30: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
aa40: 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
aa50: 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
aa60: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
aa70: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
aa80: 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
aa90: 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
aaa0: 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
aab0: 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
aac0: 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
aad0: 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
aae0: 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
aaf0: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
ab00: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
ab10: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
ab20: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
ab30: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
ab40: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
ab50: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
ab60: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f  r example, so so
ab70: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  me string variab
ab80: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  le contains text
ab90: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
aba0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
abb0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
abc0: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
abd0: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
abe0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
abf0: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
ac00: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
ac10: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
ac20: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
ac30: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
ac40: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
ac50: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
ac60: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
ac70: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
ac80: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
ac90: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
aca0: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
acb0: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
acc0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
acd0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
ace0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
acf0: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
ad00: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
ad10: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
ad20: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
ad30: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
ad40: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
ad50: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
ad60: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
ad70: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
ad80: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
ad90: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
ada0: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
adb0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
adc0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
add0: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
ade0: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
adf0: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
ae00: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
ae10: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
ae20: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
ae30: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
ae40: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
ae50: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
ae60: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
ae70: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
ae80: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
ae90: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
aea0: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
aeb0: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
aec0: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
aed0: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c  ule you.** shoul
aee0: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  d always use %q 
aef0: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
af00: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
af10: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
af20: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  .** literal..**.
af30: 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
af40: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
af50: 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
af60: 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
af70: 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
af80: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
af90: 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20  tal string.  Or 
afa0: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
afb0: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74   in the argument
afc0: 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55  .** list is a NU
afd0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
afe0: 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
aff0: 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
b000: 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75  out single.** qu
b010: 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
b020: 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
b030: 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
b040: 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
b050: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
b060: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
b070: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
b080: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
b090: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
b0a0: 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
b0b0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
b0c0: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
b0d0: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
b0e0: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
b0f0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
b100: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
b110: 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
b120: 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
b130: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
b140: 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
b150: 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
b160: 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
b170: 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
b180: 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  nter..*/.char *s
b190: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
b1a0: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
b1b0: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
b1c0: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
b1d0: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
b1e0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
b1f0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
b200: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
b210: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b220: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
b230: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
b240: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
b250: 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
b260: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
b270: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
b280: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
b290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b2a0: 20 6e 65 65 64 73 2e 20 20 54 68 65 20 64 65 66   needs.  The def
b2b0: 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
b2c0: 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65  ion.** of the me
b2d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b2e0: 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74  subsystem uses t
b2f0: 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
b300: 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72  lloc().** and fr
b310: 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
b320: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
b330: 6c 69 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65  library.  Howeve
b340: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
b350: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b360: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
b370: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
b380: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
b390: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4f  kquote> SQLITE_O
b3a0: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
b3b0: 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  ATION </blockquo
b3c0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e  te>.**.** then n
b3d0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  o implementation
b3e0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
b3f0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
b400: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e 20 20 54  by.** SQLite.  T
b410: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
b420: 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
b430: 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 65  t SQLite is.** e
b440: 78 70 65 63 74 65 64 20 74 6f 20 70 72 6f 76 69  xpected to provi
b450: 64 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65  de its own imple
b460: 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2f 0a 76 6f  mentation..*/.vo
b470: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
b480: 6f 63 28 75 6e 73 69 67 6e 65 64 20 69 6e 74 29  oc(unsigned int)
b490: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
b4a0: 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 75  realloc(void*, u
b4b0: 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a 76 6f  nsigned int);.vo
b4c0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
b4d0: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
b4e0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
b4f0: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
b500: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64  tics.**.** In ad
b510: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61  dition to the ba
b520: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61  sic three alloca
b530: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a  tion routines .*
b540: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
b550: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
b560: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
b570: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
b580: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
b590: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
b5a0: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
b5b0: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  h the SQLite.** 
b5c0: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73  sources provides
b5d0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
b5e0: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a  shown below..**.
b5f0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20  ** The first of 
b600: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
b610: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  es returns the a
b620: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20  mount of memory 
b630: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  .** currently ou
b640: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
b650: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
b660: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a  d).  The second.
b670: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c  ** returns the l
b680: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e  argest instantan
b690: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f  eous amount of o
b6a0: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65  utstanding.** me
b6b0: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77  mory.  The highw
b6c0: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
b6d0: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  et if the argume
b6e0: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20  nt is.** true.  
b6f0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
b700: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74  does not use eit
b710: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
b720: 74 69 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20  tines.** and so 
b730: 74 68 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  they do not have
b740: 20 74 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74   to be implement
b750: 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
b760: 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49  ation.** if SQLI
b770: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
b780: 4c 4c 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66  LLOCATION is def
b790: 69 6e 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75  ined.  These rou
b7a0: 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f  tines.** are pro
b7b0: 76 69 64 65 64 20 62 79 20 74 68 65 20 64 65 66  vided by the def
b7c0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73  ault memory subs
b7d0: 79 73 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f  ystem for diagno
b7e0: 73 74 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73  stic.** purposes
b7f0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 75 69 6e  ..*/.sqlite3_uin
b800: 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
b810: 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
b820: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
b830: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
b840: 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
b850: 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
b860: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
b870: 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73  llocation Alarms
b880: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
b890: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
b8a0: 5d 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  ] routine is use
b8b0: 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  d to register.**
b8c0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d   a callback on m
b8d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b8e0: 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54   events..**.** T
b8f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
b900: 73 74 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20  sters or clears 
b910: 61 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  a callbacks that
b920: 20 66 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74   fires when.** t
b930: 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  he amount of mem
b940: 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78  ory allocated ex
b950: 63 65 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64  ceeds iThreshold
b960: 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e  .  Only.** a sin
b970: 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  gle callback can
b980: 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61   be registered a
b990: 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
b9a0: 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
b9b0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
b9c0: 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
b9d0: 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
b9e0: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  back..** The cal
b9f0: 6c 62 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65  lback is disable
ba00: 64 20 62 79 20 73 65 74 74 69 6e 67 20 78 43 61  d by setting xCa
ba10: 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c  llback to a NULL
ba20: 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  .** pointer..** 
ba30: 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65  .** The paramete
ba40: 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
ba50: 63 6b 20 61 72 65 20 74 68 65 20 70 41 72 67 20  ck are the pArg 
ba60: 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61  value, the .** a
ba70: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20  mount of memory 
ba80: 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65  currently in use
ba90: 2c 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f  , and the size o
baa0: 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  f the.** allocat
bab0: 69 6f 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65  ion that provoke
bac0: 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
bad0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69   The callback wi
bae0: 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79  ll.** presumably
baf0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
bb00: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
bb10: 20 75 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65   up memory space
bb20: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
bb30: 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71  k may invoke [sq
bb40: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
bb50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
bb60: 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66  loc()].** but if
bb70: 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64   it does, no add
bb80: 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  itional callback
bb90: 73 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  s will be invoke
bba0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75  d by.** the recu
bbb0: 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  rsive calls..**.
bbc0: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
bbd0: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
bbe0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  )] interface wor
bbf0: 6b 73 20 62 79 20 72 65 67 69 73 74 65 72 69 6e  ks by registerin
bc00: 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  g.** a memory al
bc10: 61 72 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20  arm at the soft 
bc20: 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69  heap limit and i
bc30: 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  nvoking .** [sql
bc40: 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
bc50: 6f 72 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c  ory()] in the al
bc60: 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  arm callback.  A
bc70: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  pplication.** pr
bc80: 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f  ograms should no
bc90: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  t attempt to use
bca0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
bcb0: 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a  mory_alarm()].**
bcc0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 61 75   interface becau
bcd0: 73 65 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c  se doing so will
bce0: 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68 20   interfere with 
bcf0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
bd00: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
bd10: 29 5d 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e  )] module..*/.in
bd20: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
bd30: 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a  _alarm(.  void(*
bd40: 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20  xCallback)(void 
bd50: 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 75  *pArg, sqlite3_u
bd60: 69 6e 74 36 34 20 75 73 65 64 2c 20 75 6e 73 69  int64 used, unsi
bd70: 67 6e 65 64 20 69 6e 74 20 4e 29 2c 0a 20 20 76  gned int N),.  v
bd80: 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c  oid *pArg,.  sql
bd90: 69 74 65 33 5f 75 69 6e 74 36 34 20 69 54 68 72  ite3_uint64 iThr
bda0: 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a  eshold.);.../*.*
bdb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
bdc0: 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
bdd0: 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
bde0: 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  .***.** This rou
bdf0: 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
be00: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
be10: 62 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51  back with the SQ
be20: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a  Lite library.  .
be30: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
be40: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
be50: 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
be60: 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
be70: 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
be80: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
be90: 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
bea0: 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
beb0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
bec0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
bed0: 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
bee0: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
bef0: 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
bf00: 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
bf10: 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
bf20: 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
bf30: 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
bf40: 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
bf50: 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
bf60: 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
bf70: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
bf80: 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
bf90: 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
bfa0: 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
bfb0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
bfc0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
bfd0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
bfe0: 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  K to allow the a
bff0: 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
c000: 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
c010: 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
c020: 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
c030: 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
c040: 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
c050: 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
c060: 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
c070: 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
c080: 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
c090: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
c0a0: 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
c0b0: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a  n error.  .**.**
c0c0: 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   Depending on th
c0d0: 65 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53  e action, the [S
c0e0: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e  QLITE_IGNORE] an
c0f0: 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  d [SQLITE_DENY] 
c100: 72 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20  return.** codes 
c110: 6d 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74  might mean somet
c120: 68 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f  hing different o
c130: 72 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61  r they might mea
c140: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68  n the same.** th
c150: 69 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74  ing.  If the act
c160: 69 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d  ion is, for exam
c170: 70 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20  ple, to perform 
c180: 61 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f  a delete opertio
c190: 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49  n,.** then [SQLI
c1a0: 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b  TE_IGNORE] and [
c1b0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74  SQLITE_DENY] bot
c1c0: 68 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74  h cause the stat
c1d0: 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f  ement compilatio
c1e0: 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74  n.** to fail wit
c1f0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74  h an error.  But
c200: 20 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69   if the action i
c210: 73 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63  s to read a spec
c220: 69 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66  ific column.** f
c230: 72 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74  rom a specific t
c240: 61 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49  able, then [SQLI
c250: 54 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61  TE_DENY] will ca
c260: 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a  use the entire.*
c270: 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66  * statement to f
c280: 61 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f  ail but [SQLITE_
c290: 49 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75  IGNORE] will cau
c2a0: 73 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  se a NULL value 
c2b0: 74 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e  to be.** read in
c2c0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74  stead of the act
c2d0: 75 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  ual column value
c2e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
c2f0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
c300: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
c310: 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
c320: 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   of.** the third
c330: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
c340: 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
c350: 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
c360: 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63  face..** The sec
c370: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
c380: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
c390: 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20   an integer .** 
c3a0: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
c3b0: 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
c3c0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
c3d0: 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
c3e0: 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72  .** to be author
c3f0: 69 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c  ized.  The avail
c400: 61 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  able action code
c410: 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s are.** [SQLITE
c420: 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74  _COPY | document
c430: 65 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20  ed separately]. 
c440: 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
c450: 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61  gh sixth.** para
c460: 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61  meters to the ca
c470: 6c 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e  llback are strin
c480: 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
c490: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
c4a0: 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
c4b0: 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
c4c0: 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
c4d0: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
c4e0: 75 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72  used when prepar
c4f0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
c500: 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
c510: 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
c520: 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
c530: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
c540: 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
c550: 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
c560: 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
c570: 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
c580: 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
c590: 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
c5a0: 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
c5b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
c5c0: 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
c5d0: 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
c5e0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
c5f0: 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
c600: 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
c610: 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
c620: 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
c630: 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
c640: 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
c650: 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
c660: 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
c670: 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
c680: 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
c690: 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
c6a0: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
c6b0: 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
c6c0: 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
c6d0: 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
c6e0: 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
c6f0: 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
c700: 70 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69  prepared that di
c710: 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
c720: 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c  ng.** except SEL
c730: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  ECT statements. 
c740: 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73   .**.** Only a s
c750: 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
c760: 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
c770: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
c780: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
c790: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
c7a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
c7b0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
c7c0: 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
c7d0: 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20  evious call.  A 
c7e0: 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
c7f0: 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
c800: 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
c810: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
c820: 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
c830: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
c840: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ULL..**.** Note 
c850: 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
c860: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
c870: 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
c880: 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
c890: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
c8a0: 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
c8b0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
c8c0: 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
c8d0: 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
c8e0: 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
c8f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
c900: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
c910: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
c920: 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
c930: 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
c940: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
c950: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
c960: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
c970: 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
c980: 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
c990: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
c9a0: 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
c9b0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
c9c0: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
c9d0: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
c9e0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
c9f0: 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
ca00: 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
ca10: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
ca20: 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
ca30: 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
ca40: 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
ca50: 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
ca60: 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
ca70: 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
ca80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
ca90: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
caa0: 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
cab0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
cac0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
cad0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64  formation..*/.#d
cae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
caf0: 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
cb00: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
cb10: 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
cb20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cb30: 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
cb40: 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
cb50: 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
cb60: 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
cb70: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
cb80: 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
cb90: 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
cba0: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
cbb0: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
cbc0: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
cbd0: 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
cbe0: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
cbf0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
cc00: 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61  authorizer certa
cc10: 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
cc20: 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
cc30: 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
cc40: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
cc50: 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
cc60: 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
cc70: 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
cc80: 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
cc90: 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
cca0: 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
ccb0: 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
ccc0: 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
ccd0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
cce0: 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
ccf0: 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
cd00: 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
cd10: 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
cd20: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
cd30: 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  be .** authorize
cd40: 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
cd50: 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
cd60: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
cd70: 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ion callback.** 
cd80: 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
cd90: 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
cda0: 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
cdb0: 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
cdc0: 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
cdd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
cde0: 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35  arameter.  The 5
cdf0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
ce00: 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
ce10: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
ce20: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
ce30: 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
ce40: 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e  "temp", .** etc.
ce50: 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
ce60: 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
ce70: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
ce80: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
ce90: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
cea0: 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
ceb0: 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
cec0: 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
ced0: 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
cee0: 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
cef0: 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
cf00: 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
cf10: 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a  directly from .*
cf20: 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
cf30: 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
cf40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
cf50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
cf60: 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
cf70: 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
cf80: 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
cf90: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
cfa0: 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
cfb0: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
cfc0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
cfd0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
cfe0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
cff0: 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
d000: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
d010: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d020: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d030: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
d040: 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
d050: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
d060: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
d070: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d080: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
d090: 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
d0a0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d0b0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
d0c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d0d0: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
d0e0: 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
d0f0: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
d100: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
d110: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d120: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
d130: 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
d140: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
d150: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d160: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d170: 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
d180: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
d190: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
d1a0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
d1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d1c0: 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
d1d0: 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
d1e0: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
d1f0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
d210: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
d220: 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
d230: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
d240: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
d250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
d260: 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
d270: 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
d280: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
d290: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
d2a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
d2b0: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
d2c0: 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
d2d0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d2e0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d2f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
d300: 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
d310: 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
d320: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
d330: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
d340: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
d350: 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
d360: 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
d370: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
d380: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
d3a0: 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
d3b0: 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
d3c0: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
d3d0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
d3e0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
d3f0: 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
d400: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
d410: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
d420: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d430: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
d440: 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
d450: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
d460: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
d470: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
d480: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
d490: 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
d4a0: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
d4b0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
d4c0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
d4d0: 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
d4e0: 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
d4f0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
d500: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
d510: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d520: 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
d530: 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
d540: 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
d550: 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
d560: 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
d570: 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
d580: 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
d590: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
d5a0: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
d5b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d5c0: 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
d5d0: 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
d5e0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d5f0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
d600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d610: 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
d620: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
d630: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
d640: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
d650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d660: 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
d670: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
d680: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
d690: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
d6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d6b0: 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
d6c0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
d6d0: 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
d6e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
d6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
d700: 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
d710: 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
d720: 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
d730: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
d740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
d750: 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
d760: 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
d770: 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
d780: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
d7a0: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
d7b0: 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
d7c0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
d7d0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
d7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
d7f0: 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
d800: 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
d810: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
d820: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
d830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
d840: 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
d850: 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
d860: 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
d870: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
d880: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
d890: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
d8a0: 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
d8b0: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
d8c0: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
d8d0: 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
d8e0: 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
d8f0: 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
d900: 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
d910: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
d920: 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
d930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
d940: 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
d950: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
d960: 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
d970: 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
d980: 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
d990: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
d9a0: 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
d9b0: 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
d9c0: 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
d9d0: 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
d9e0: 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
d9f0: 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
da00: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63  ements..** The c
da10: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
da20: 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
da30: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
da40: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20  s invoked.** at 
da50: 74 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74  the first [sqlit
da60: 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74  e3_step()] for t
da70: 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
da80: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
da90: 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
daa0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
dab0: 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
dac0: 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
dad0: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
dae0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
daf0: 66 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63  finishes and inc
db00: 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ludes.** informa
db10: 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67  tion on how long
db20: 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
db30: 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ran..**.** The s
db40: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
db50: 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c   API is currentl
db60: 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  y considered exp
db70: 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a  erimental and.**
db80: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
db90: 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  hange..*/.void *
dba0: 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
dbb0: 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
dbc0: 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
dbd0: 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
dbe0: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
dbf0: 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
dc00: 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
dc10: 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
dc20: 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
dc30: 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
dc40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dc50: 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
dc60: 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
dc70: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e  This routine con
dc80: 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61  figures a callba
dc90: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68  ck function - th
dca0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
dcb0: 61 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73  ack - that.** is
dcc0: 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
dcd0: 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
dce0: 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
dcf0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
dd00: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
dd10: 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
dd20: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
dd30: 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
dd40: 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a  use for this .**
dd50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
dd60: 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
dd70: 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
dd80: 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
dd90: 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
dda0: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
ddb0: 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
ddc0: 4e 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  N virtual machin
ddd0: 65 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68  e opcodes,.** wh
dde0: 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
ddf0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
de00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54  this function. T
de10: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
de20: 62 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69  back.** itself i
de30: 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
de40: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
de50: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
de60: 69 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a  ion. The fourth.
de70: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  ** argument to t
de80: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
de90: 61 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70  a void pointer p
dea0: 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
deb0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
dec0: 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20  * function each 
ded0: 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b  time it is invok
dee0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ed..**.** If a c
def0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
df00: 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
df10: 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73  3_step()], or [s
df20: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
df30: 28 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  ()].** results i
df40: 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f  n fewer than N o
df50: 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65  pcodes being exe
df60: 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  cuted, then the 
df70: 70 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c  progress .** cal
df80: 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69  lback is never i
df90: 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f  nvoked..** .** O
dfa0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
dfb0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66  gress callback f
dfc0: 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
dfd0: 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61  egistered for ea
dfe0: 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ch.** open datab
dff0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
e000: 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73   Every call to s
e010: 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
e020: 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65  handler().** ove
e030: 72 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75  rwrites the resu
e040: 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69  lts of the previ
e050: 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20  ous call..** To 
e060: 72 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72  remove the progr
e070: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74  ess callback alt
e080: 6f 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55  ogether, pass NU
e090: 4c 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  LL as the third.
e0a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  ** argument to t
e0b0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
e0c0: 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
e0d0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
e0e0: 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
e0f0: 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
e100: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
e110: 20 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69   query is immedi
e120: 61 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64  ately terminated
e130: 20 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73   and any databas
e140: 65 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64  e changes rolled
e150: 20 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f   back..** The co
e160: 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65  ntaining [sqlite
e170: 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
e180: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a  te3_step()], or.
e190: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
e1a0: 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65  table()] call re
e1b0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54  turns SQLITE_INT
e1c0: 45 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66  ERRUPT.   This f
e1d0: 65 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65  eature.** can be
e1e0: 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
e1f0: 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  le, to implement
e200: 20 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75   the "Cancel" bu
e210: 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f  tton on a.** pro
e220: 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
e230: 20 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f   in a GUI..*/.vo
e240: 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
e250: 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
e260: 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
e270: 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
e280: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e290: 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
e2a0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
e2b0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20  tion.**.** Open 
e2c0: 74 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62  the sqlite datab
e2d0: 61 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61  ase file "filena
e2e0: 6d 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e  me".  The "filen
e2f0: 61 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a  ame" is UTF-8.**
e300: 20 65 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c   encoded for sql
e310: 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
e320: 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 69  UTF-16 encoded i
e330: 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
e340: 65 20 6f 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73  e order.** for s
e350: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
e360: 20 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20    An [sqlite3*] 
e370: 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e  handle is return
e380: 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
e390: 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72  n.** if an error
e3a0: 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68 65 20   occurs. If the 
e3b0: 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
e3c0: 65 64 20 28 6f 72 20 63 72 65 61 74 65 64 29 20  ed (or created) 
e3d0: 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a  successfully,.**
e3e0: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   then [SQLITE_OK
e3f0: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f  ] is returned. O
e400: 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
e410: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
e420: 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  ed. The.** [sqli
e430: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
e440: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
e450: 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20  16()]  routines 
e460: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
e470: 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
e480: 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
e490: 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
e4a0: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  error..**.** If 
e4b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
e4c0: 65 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  e does not exist
e4d0: 2c 20 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74  , then a new dat
e4e0: 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
e4f0: 65 61 74 65 64 0a 2a 2a 20 61 73 20 6e 65 65 64  eated.** as need
e500: 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
e510: 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
e520: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
e530: 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
e540: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 69 73  qlite3_open() is
e550: 20 63 61 6c 6c 65 64 20 61 6e 64 20 55 54 46 2d   called and UTF-
e560: 31 36 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  16 if sqlite3_op
e570: 65 6e 31 36 20 69 73 20 75 73 65 64 2e 0a 2a 2a  en16 is used..**
e580: 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
e590: 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
e5a0: 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
e5b0: 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20  ened, resources 
e5c0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
e5d0: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  th the [sqlite3*
e5e0: 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
e5f0: 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70  be released by p
e600: 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20  assing it to.** 
e610: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
e620: 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
e630: 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
e640: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e650: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
e660: 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
e670: 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
e680: 20 65 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20   except that.** 
e690: 70 72 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64  provides two add
e6a0: 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
e6b0: 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
e6c0: 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74  l control over t
e6d0: 68 65 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61  he.** new databa
e6e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
e6f0: 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
e700: 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f  ter can be one o
e710: 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  f:.**.** <ol>.**
e720: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e730: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a  PEN_READONLY].**
e740: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e750: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a  PEN_READWRITE].*
e760: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e770: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
e780: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
e790: 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  REATE].** </ol>.
e7a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
e7b0: 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20  value opens the 
e7c0: 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e  database read-on
e7d0: 6c 79 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  ly.  If the data
e7e0: 62 61 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  base does.** not
e7f0: 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
e800: 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
e810: 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65  eturned.  The se
e820: 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e  cond option open
e830: 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
e840: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
e850: 64 20 77 72 69 74 69 6e 67 20 62 75 74 20 74 68  d writing but th
e860: 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
e870: 61 6c 72 65 61 64 79 0a 2a 2a 20 65 78 69 73 74  already.** exist
e880: 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20   or an error is 
e890: 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74  returned.  The t
e8a0: 68 69 72 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e  hird option open
e8b0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
e8c0: 2a 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  * for reading an
e8d0: 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72  d writing and cr
e8e0: 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64  eates it if it d
e8f0: 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
e900: 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68  exist..** The th
e910: 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62  ird options is b
e920: 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
e930: 75 73 65 64 20 61 6c 77 61 79 73 20 66 6f 72 20  used always for 
e940: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
e950: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  * and sqlite3_op
e960: 65 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  en16()..**.** Th
e970: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
e980: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
e990: 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
e9a0: 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
e9c0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
e9d0: 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
e9e0: 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61  stem .** interfa
e9f0: 63 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20  ce that the new 
ea00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ea10: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
ea20: 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
ea30: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
ea40: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
ea50: 65 6e 20 61 20 64 65 66 61 75 6c 74 20 73 75 69  en a default sui
ea60: 74 61 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  table for.** the
ea70: 20 68 6f 73 74 20 65 6e 76 69 72 6f 6e 6d 65 6e   host environmen
ea80: 74 20 69 73 20 73 75 62 73 74 69 74 75 74 65 64  t is substituted
ea90: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 6f 20  ..**.** Note to 
eaa0: 77 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 20 20  windows users:  
eab0: 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
eac0: 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
ead0: 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
eae0: 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
eaf0: 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
eb00: 6e 6f 74 20 77 68 61 74 65 76 65 72 20 63 6f 64  not whatever cod
eb10: 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
eb20: 6c 79 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 20  ly.** defined.  
eb30: 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
eb40: 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
eb50: 61 6c 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  al characters mu
eb60: 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
eb70: 2a 2a 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ** to UTF-8 prio
eb80: 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
eb90: 6d 20 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f 6f  m into sqlite3_o
eba0: 70 65 6e 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  pen()..*/.int sq
ebb0: 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
ebc0: 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
ebd0: 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
ebe0: 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
ebf0: 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
ec00: 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
ec10: 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
ec20: 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
ec30: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
ec40: 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
ec50: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
ec60: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
ec70: 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
ec80: 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
ec90: 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
eca0: 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
ecb0: 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
ecc0: 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
ecd0: 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
ece0: 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
ecf0: 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
ed00: 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
ed10: 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
ed20: 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
ed30: 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
ed40: 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
ed50: 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
ed60: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
ed70: 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
ed80: 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
ed90: 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
eda0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
edb0: 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
edc0: 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54  Messages.**.** T
edd0: 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
ede0: 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
edf0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
ee00: 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ic.** [SQLITE_OK
ee10: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20   | result code] 
ee20: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
ee30: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
ee40: 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
ee50: 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
ee60: 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
ee70: 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
ee80: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
ee90: 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64  h [sqlite3] hand
eea0: 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61 20 70  le 'db'.  If a p
eeb0: 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
eec0: 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20  iled but the.** 
eed0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
eee0: 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
eef0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
ef00: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
ef10: 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e  rcode().** is un
ef20: 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  defined. .**.** 
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
ef40: 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
ef50: 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
ef60: 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61  rn English-langa
ef70: 75 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  uge.** text that
ef80: 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
ef90: 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
efa0: 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65  UTF8 or UTF16 re
efb0: 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
efc0: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
efd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
efe0: 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
eff0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54  d internally.  T
f000: 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61  he .** string ma
f010: 79 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  y be overwritten
f020: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
f030: 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  by subsequent ca
f040: 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a  lls to SQLite.**
f050: 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
f060: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  ions..**.** Call
f070: 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65  s to many sqlite
f080: 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65  3_* functions se
f090: 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  t the error code
f0a0: 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75   and string retu
f0b0: 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
f0c0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
f0d0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
f0e0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
f0f0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
f100: 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65  (overwriting the
f110: 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73   previous values
f120: 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  ). Note that cal
f130: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
f140: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73  rrcode()],.** [s
f150: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
f160: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
f170: 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73  rrmsg16()] thems
f180: 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66  elves do not aff
f190: 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ect the.** resul
f1a0: 74 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76  ts of future inv
f1b0: 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73  ocations.  Calls
f1c0: 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73   to API routines
f1d0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74   that do not ret
f1e0: 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  urn.** an error 
f1f0: 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 73 3a 20  code (examples: 
f200: 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
f210: 75 6e 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  unt()] or [sqlit
f220: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 20 64  e3_mprintf()]) d
f230: 6f 0a 2a 2a 20 6e 6f 74 20 63 68 61 6e 67 65 20  o.** not change 
f240: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72  the error code r
f250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
f260: 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 41  routine..**.** A
f270: 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72  ssuming no other
f280: 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c   intervening sql
f290: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73  ite3_* API calls
f2a0: 20 61 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65   are made, the e
f2b0: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74  rror.** code ret
f2c0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
f2d0: 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  nction is associ
f2e0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
f2f0: 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74  me error as.** t
f300: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
f310: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
f320: 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
f330: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
f340: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
f350: 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
f360: 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
f370: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
f380: 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
f390: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
f3a0: 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
f3b0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
f3c0: 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
f3d0: 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
f3e0: 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** Instance of t
f3f0: 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
f400: 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20  sent single SQL 
f410: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69  statements.  Thi
f420: 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c  s.** is variousl
f430: 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
f440: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
f450: 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70  " or a .** "comp
f460: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
f470: 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
f480: 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
f490: 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  ** .** The life 
f4a0: 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
f4b0: 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
f4c0: 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
f4d0: 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
f4e0: 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
f4f0: 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
f500: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
f510: 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
f520: 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
f530: 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
f540: 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
f550: 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a  ameters using.**
f560: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
f570: 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
f580: 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66  e3_bind_* interf
f590: 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  aces]..** <li> R
f5a0: 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
f5b0: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
f5c0: 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
f5d0: 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
f5e0: 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
f5f0: 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
f600: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
f610: 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
f620: 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
f630: 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
f640: 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
f650: 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
f660: 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
f670: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
f680: 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
f690: 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
f6a0: 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
f6b0: 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
f6c0: 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
f6d0: 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
f6e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
f6f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
f700: 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
f710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f720: 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
f730: 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
f740: 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
f750: 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
f760: 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
f770: 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
f780: 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
f790: 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
f7a0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a  ese routines. .*
f7b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
f7c0: 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20  rgument "db" is 
f7d0: 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51  an [sqlite3 | SQ
f7e0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 68 61  Lite database ha
f7f0: 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e  ndle] .** obtain
f800: 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20  ed from a prior 
f810: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
f820: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
f830: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
f840: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
f850: 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
f860: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
f870: 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
f880: 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
f890: 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
f8a0: 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
f8b0: 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
f8c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
f8d0: 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
f8e0: 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
f8f0: 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
f900: 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
f910: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
f920: 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
f930: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
f940: 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
f950: 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f  ess.** than zero
f960: 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
f970: 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
f980: 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
f990: 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79 74  tor.  If.** nByt
f9a0: 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
f9b0: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
f9c0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
f9d0: 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65   of .** bytes re
f9e0: 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
f9f0: 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
fa00: 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
fa10: 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
fa20: 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
fa30: 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 63 68   first '\000' ch
fa40: 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75  aracter or .** u
fa50: 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74  ntil the nByte-t
fa60: 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
fa70: 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
fa80: 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
fa90: 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
faa0: 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
fab0: 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
fac0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51 4c  the first.** SQL
fad0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
fae0: 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  ql.  This routin
faf0: 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20  e only compiles 
fb00: 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
fb10: 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20  ent.** in zSql, 
fb20: 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
fb30: 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
fb40: 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
fb50: 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
fb60: 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
fb70: 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
fb80: 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  iled .** [sqlite
fb90: 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61  3_stmt | SQL sta
fba0: 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72 65  tement structure
fbb0: 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
fbc0: 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
fbd0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
fbe0: 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69  .  Or if there i
fbf0: 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
fc00: 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65  tmt may be.** se
fc10: 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  t to NULL.  If t
fc20: 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
fc30: 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20 28  ntained no SQL (
fc40: 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
fc50: 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74 72  and.** empty str
fc60: 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
fc70: 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
fc80: 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20  s set to NULL.  
fc90: 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 70  The calling.** p
fca0: 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
fcb0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
fcc0: 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
fcd0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
fce0: 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
fcf0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
fd00: 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
fd10: 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
fd20: 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
fd30: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
fd40: 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
fd50: 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  se an .** [SQLIT
fd60: 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
fd70: 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
fd80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
fd90: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
fda0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
fdb0: 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
fdc0: 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
fdd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
fde0: 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
fdf0: 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
fe00: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
fe10: 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
fe20: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
fe30: 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
fe40: 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
fe50: 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
fe60: 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
fe70: 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
fe80: 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
fe90: 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
fea0: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
feb0: 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
fec0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a  a copy of the .*
fed0: 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
fee0: 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
fef0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
ff00: 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
ff10: 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
ff20: 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
ff30: 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
ff40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
ff50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
ff60: 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
ff70: 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
ff80: 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
ff90: 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
ffa0: 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
ffb0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
ffc0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
ffd0: 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
ffe0: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
fff0: 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
10000 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
10010 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
10020 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a 2a  anged in a way.*
10030 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  * that makes the
10040 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
10050 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
10060 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
10070 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
10080 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
10090 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
100a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
100b0 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
100c0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
100d0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
100e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
100f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
10100 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
10110 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
10120 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
10130 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
10140 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
10150 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 61 72   text of the par
10160 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74 68  sing.** error th
10170 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
10180 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
10190 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
101a0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
101b0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
101c0 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74  curs, .** [sqlit
101d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
101e0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
101f0 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b  e detailed .** [
10200 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
10210 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
10220 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
10230 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
10240 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 73   result codes] s
10250 75 63 68 20 61 73 20 64 69 72 65 63 74 6c 79 2e  uch as directly.
10260 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62  .** The legacy b
10270 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
10280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
10290 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
102a0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a  urn a generic.**
102b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
102c0 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20  result code and 
102d0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74  you would have t
102e0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
102f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
10300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
10310 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
10320 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
10330 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
10340 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  m..** With the "
10350 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65  v2" prepare inte
10360 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
10370 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
10380 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a  r the error is.*
10390 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  * returned immed
103a0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
103b0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
103c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
103d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
103e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
103f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
10400 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
10410 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
10420 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
10430 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
10440 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
10450 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10460 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
10470 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
10480 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
10490 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
104a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
104b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
104c0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
104d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
104e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
104f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
10500 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
10510 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
10520 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
10530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
10540 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
10550 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
10560 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
10570 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
10580 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
10590 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
105a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
105b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
105c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
105d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
105e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
105f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
10600 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
10610 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
10620 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
10630 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
10640 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
10650 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
10660 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
10670 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
10680 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
10690 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
106a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
106b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
106c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
106d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
106e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
106f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
10700 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
10710 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
10720 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
10730 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
10740 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
10750 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
10760 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
10770 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
10780 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
10790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
107a0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
107b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
107c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
107d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
107e0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
107f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
10800 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
10810 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
10820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
10830 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
10840 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
10850 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
10860 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
10870 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
10880 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
10890 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
108a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
108b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
108c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
108d0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
108e0 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c  3REF:  Dynamical
108f0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
10900 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  bject.**.** SQLi
10910 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
10920 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76  typing for the v
10930 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
10940 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a 2a    Values can .**
10950 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
10960 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
10970 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
10980 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20 57  OBs, or NULL.  W
10990 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20 61  hen.** passing a
109a0 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e 74  round values int
109b0 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76 61  ernally, each va
109c0 6c 75 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  lue is represent
109d0 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73 74  ed as.** an inst
109e0 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
109f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
10a00 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
10a10 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
10a20 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
10a30 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e  PI3REF:  SQL Fun
10a40 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
10a50 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
10a60 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
10a70 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
10a80 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
10a90 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
10aa0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
10ab0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
10ac0 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63 74  o such an object
10ad0 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   is the.** first
10ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75 73   parameter to us
10af0 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  er-defined SQL f
10b00 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70  unctions..*/.typ
10b10 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10b20 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
10b30 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
10b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42  .** CAPI3REF:  B
10b50 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
10b60 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
10b70 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ents.**.** In th
10b80 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
10b90 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
10ba0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
10bb0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
10bc0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c  ** one or more l
10bd0 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72  iterals can be r
10be0 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61  eplace by a para
10bf0 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20  meter in one of 
10c00 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a 0a  these.** forms:.
10c10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
10c20 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
10c30 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41  NNN.** <li>  :AA
10c40 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a  A.** <li>  @AAA.
10c50 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
10c60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
10c70 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
10c80 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
10c90 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
10ca0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41  r literal,.** AA
10cb0 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  A is an alphanum
10cc0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20  eric identifier 
10cd0 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72  and VVV is a var
10ce0 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72  iable name accor
10cf0 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ding.** to the s
10d00 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74  yntax rules of t
10d10 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69  he TCL programmi
10d20 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a 20  ng language..** 
10d30 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
10d40 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28  ese parameters (
10d50 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
10d60 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
10d70 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
10d80 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
10d90 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
10da0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
10db0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
10dc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10dd0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
10de0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c  _*() routines al
10df0 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74 65  ways is a pointe
10e00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
10e10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
10e20 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  t returned from 
10e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
10e40 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74 73  _v2()] or.** its
10e50 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65 20   variants.  The 
10e60 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
10e70 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
10e80 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
10e90 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68 65   to be set.  The
10ea0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
10eb0 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65 78   has.** an index
10ec0 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65 20   of 1. When the 
10ed0 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61 6d  same named param
10ee0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
10ef0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
10f00 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  ond.** and subse
10f10 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
10f20 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
10f30 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
10f40 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
10f50 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72  .  The index for
10f60 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  .** named parame
10f70 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
10f80 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
10f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
10fa0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
10fb0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
10fc0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f  d.  The index fo
10fd0 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72 61  r "?NNN".** para
10fe0 6d 65 74 65 73 20 69 73 20 74 68 65 20 76 61 6c  metes is the val
10ff0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
11000 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
11010 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
11020 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
11030 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  me.** parameter 
11040 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
11050 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61  BLE_NUMBER (defa
11060 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
11070 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d  .** See <a href=
11080 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69  "limits.html">li
11090 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f  mits.html</a> fo
110a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
110b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
110c0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
110d0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
110e0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
110f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
11100 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74  In those.** rout
11110 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
11120 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
11130 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
11140 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
11150 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72  es.** in the par
11160 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
11170 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
11180 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11190 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a 2a   bytes in the.**
111a0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
111b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
111c0 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d 62  cters.  The numb
111d0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64  er.** of bytes d
111e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
111f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
11200 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f  tor at the end o
11210 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  f strings..** If
11220 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
11230 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
11240 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
11250 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
11260 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
11270 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
11280 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
11290 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  r..**.** The fif
112a0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
112b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
112c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
112d0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
112e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
112f0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
11300 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
11310 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
11320 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74  B or.** text aft
11330 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
11340 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
11350 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
11360 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
11370 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
11380 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
11390 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79  then the library
113a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
113b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  e information.**
113c0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
113d0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
113e0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
113f0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20 49   to be freed.  I
11400 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20 61  f the.** fifth a
11410 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
11420 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
11430 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20 53  ANSIENT], then S
11440 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 0a  QLite makes its.
11450 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ** own private c
11460 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
11470 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
11480 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ore the sqlite3_
11490 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75 74  bind_*().** rout
114a0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
114b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
114c0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
114d0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
114e0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e 20  LOB of length n 
114f0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
11500 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  d with zeros.  A
11510 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
11520 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
11530 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
11540 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
11550 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69  old it size) whi
11560 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
11570 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
11580 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
11590 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
115a0 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
115b0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
115c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
115d0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
115e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
115f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
11600 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
11610 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
11620 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
11630 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
11640 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
11650 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
11660 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
11670 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
11680 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
11690 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
116a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
116b0 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
116c0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
116d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
116e0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
116f0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
11700 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
11710 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
11720 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
11730 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
11740 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
11750 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
11760 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
11770 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
11780 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
11790 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
117a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
117b0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
117c0 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
117d0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
117e0 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73   if malloc fails
117f0 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ..** [SQLITE_MIS
11800 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USE] is returned
11810 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
11820 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
11830 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61   a virtual.** ma
11840 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
11850 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
11860 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
11870 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
11880 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
11890 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
118a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
118b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
118c0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
118d0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
118e0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
118f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
11900 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
11910 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
11920 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
11930 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
11940 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
11950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
11960 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
11970 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
11980 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
11990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
119a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
119b0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
119c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
119d0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
119e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
119f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
11a00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
11a10 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
11a20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
11a30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
11a40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
11a50 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
11a60 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
11a70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
11a80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
11a90 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
11aa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
11ab0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
11ac0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
11ad0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73 0a  Host Parameters.
11ae0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
11af0 20 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70 61   largest host pa
11b00 72 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69 6e  rameter index in
11b10 20 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64   the precompiled
11b20 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e   statement given
11b30 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75 6d  .** as the argum
11b40 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20 68  ent.  When the h
11b50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 61  ost parameters a
11b60 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20  re of the forms 
11b70 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20 6f  like ":AAA".** o
11b80 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65 79  r "?", then they
11b90 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65   are assigned se
11ba0 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73  quential increas
11bb0 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69  ing numbers begi
11bc0 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e  nning.** with on
11bd0 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20  e, so the value 
11be0 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
11bf0 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
11c00 74 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a 2a  ters.  However.*
11c10 2a 20 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f  * if the same ho
11c20 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
11c30 65 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70  e is used multip
11c40 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f  le times, each o
11c50 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20  ccurrance.** is 
11c60 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  given the same n
11c70 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61  umber, so the va
11c80 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lue returned in 
11c90 74 68 61 74 20 63 61 73 65 20 69 73 20 74 68 65  that case is the
11ca0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e   number.** of un
11cb0 69 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65  ique host parame
11cc0 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20 68  ter names.  If h
11cd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ost parameters o
11ce0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
11cf0 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28 77  ".** are used (w
11d00 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  here NNN is an i
11d10 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68 65  nteger) then the
11d20 72 65 20 6d 69 67 68 74 20 62 65 20 67 61 70 73  re might be gaps
11d30 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   in the.** numbe
11d40 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61 6c  ring and the val
11d50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
11d60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
11d70 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
11d80 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d 65  e.** host parame
11d90 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61 72  ter with the lar
11da0 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75 65  gest index value
11db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 70  ..**.** The prep
11dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d  ared statement m
11dd0 75 73 74 20 6e 6f 74 20 6e 6f 74 20 62 65 20 5b  ust not not be [
11de0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
11df0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a   | finalized].**
11e00 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72   prior to this r
11e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e  outine returnnin
11e20 67 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68  g.  Otherwise th
11e30 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
11e40 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70  defined.** and p
11e50 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
11e60 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ble..*/.int sqli
11e70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
11e80 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
11e90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
11ea0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
11eb0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
11ec0 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  er.**.** This ro
11ed0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
11ee0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
11ef0 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 20  ame of the n-th 
11f00 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 0a  parameter in a .
11f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
11f20 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
11f30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20  ement]..** Host 
11f40 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
11f50 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72  e form ":AAA" or
11f60 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56   "@AAA" or "$VVV
11f70 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a  " have a name.**
11f80 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
11f90 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22  ring ":AAA" or "
11fa0 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e  @AAA" or "$VVV".
11fb0 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77    .** In other w
11fc0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
11fd0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
11fe0 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "@".** is includ
11ff0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
12000 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
12010 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
12020 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20  m "?" or "?NNN" 
12030 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a  have no name..**
12040 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 62 6f  .** The first bo
12050 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 68 61  und parameter ha
12060 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
12070 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
12080 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
12090 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
120a0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
120b0 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c 65 73  meter is nameles
120c0 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20  s,.** then NULL 
120d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
120e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
120f0 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e 20 74  g is always in t
12100 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f  he.** UTF-8 enco
12110 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
12120 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
12130 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20   was originally 
12140 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61 73 20  specified.** as 
12150 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
12160 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
12170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
12180 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
12190 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
121a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
121b0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
121c0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
121e0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
121f0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
12200 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  Name.**.** This 
12210 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12220 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68  the index of a h
12230 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69  ost parameter wi
12240 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d  th the given nam
12250 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d  e..** The name m
12260 75 73 74 20 6d 61 74 63 68 20 65 78 61 63 74 6c  ust match exactl
12270 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 6d 65  y.  If no parame
12280 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76  ter with the giv
12290 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66  en name is .** f
122a0 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 20  ound, return 0. 
122b0 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   Parameter names
122c0 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a   must be UTF8..*
122d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
122e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
122f0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
12300 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
12310 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
12320 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
12330 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
12340 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
12350 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79  t.**.** Contrary
12360 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
12370 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
12380 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
12390 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74  s not.** reset t
123a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
123b0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
123c0 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69  ] on a .** [sqli
123d0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
123e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
123f0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
12400 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c  e to.** reset al
12410 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
12420 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
12430 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
12440 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
12450 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
12460 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
12470 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
12480 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
12490 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  * Return the num
124a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
124b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
124c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
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 20 54 68  L statement]. Th
12500 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
12510 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
12520 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
12530 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
12540 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
12550 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
12560 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69  an UPDATE)..*/.i
12570 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
12580 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
12590 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
125a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
125b0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
125c0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
125d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
125e0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
125f0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
12600 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
12610 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
12620 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
12630 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  T statement.  Th
12640 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
12650 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
12660 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
12670 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 38  ointer to a UTF8
12680 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71 6c 69   string and sqli
12690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
126a0 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  6().** returns a
126b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
126c0 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  F16 string.  The
126d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
126e0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   is the.** [sqli
126f0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61  te3_stmt | prepa
12700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
12710 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
12720 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
12730 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ent..** The seco
12740 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
12750 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  the column numbe
12760 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  r.  The left-mos
12770 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e  t column is.** n
12780 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
12790 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
127a0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
127b0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
127c0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
127d0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
127e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
127f0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
12800 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
12810 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  ].** or until th
12820 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69  e next call sqli
12830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
12840 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
12850 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20  umn_name16().** 
12860 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
12870 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  mn..*/.const cha
12880 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
12890 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
128a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
128b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
128c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
128d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
128e0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
128f0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
12900 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
12910 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54  y Result.**.** T
12920 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
12930 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
12940 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
12950 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
12960 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
12970 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
12980 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  lt of a SELECT s
12990 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
129a0 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
129b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
129c0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
129d0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
129e0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
129f0 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36   a UTF8 or UTF16
12a00 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
12a10 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
12a20 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
12a30 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
12a40 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
12a50 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
12a60 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
12a70 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
12a80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
12a90 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
12aa0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
12ab0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
12ac0 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ntil.** the [sql
12ad0 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
12ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12af0 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
12b00 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
12b10 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
12b20 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
12b30 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
12b40 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
12b50 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
12b60 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
12b70 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
12b80 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
12b90 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
12ba0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
12bb0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
12bc0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
12bd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12be0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
12bf0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 0a  ing calls is a .
12c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
12c10 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
12c20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
12c30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
12c40 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
12c50 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
12c60 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
12c70 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
12c80 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
12c90 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
12ca0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
12cb0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
12cc0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
12cd0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
12ce0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
12cf0 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79  n.** or subquery
12d00 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
12d10 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
12d20 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
12d30 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
12d40 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73  n NULL. Otherwis
12d50 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
12d60 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  he .** name of t
12d70 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
12d80 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20  base, table and 
12d90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
12da0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  y result.** colu
12db0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
12dc0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   from..**.** As 
12dd0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
12de0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
12df0 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
12e00 20 22 31 36 22 20 72 65 74 75 72 6e 20 55 54 46   "16" return UTF
12e10 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73  -16.** encoded s
12e20 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
12e30 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
12e40 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
12e50 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
12e60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
12e70 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
12e80 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
12e90 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  he .** SQLITE_EN
12ea0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
12eb0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
12ec0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
12ed0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
12ee0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
12ef0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
12f00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
12f10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
12f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
12f30 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
12f40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
12f50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
12f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
12f70 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
12f80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
12f90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
12fa0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
12fb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
12fc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
12fd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
12fe0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
12ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
13000 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
13010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
13020 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
13030 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
13040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13050 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
13060 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
13070 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ult.**.** The fi
13080 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
13090 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
130a0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
130b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20  statement]. .** 
130c0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
130d0 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73 74  t is a SELECT st
130e0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
130f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
13100 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  e .** returned r
13110 65 73 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68  esult set  of th
13120 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
13130 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
13140 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
13150 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
13160 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
13170 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
13180 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
13190 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65  returned. If the
131a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
131b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
131c0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
131d0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
131e0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
131f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
13200 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
13210 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
13220 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20   UTF-8 encoded. 
13230 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a  For example, in.
13240 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
13250 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
13260 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
13270 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
13280 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
13290 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
132a0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
132b0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
132c0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
132d0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
132e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
132f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
13300 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
13310 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
13320 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
13330 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
13340 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
13350 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
13360 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
13370 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
13380 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
13390 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
133a0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
133b0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
133c0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
133d0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
133e0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
133f0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
13400 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
13410 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
13420 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
13430 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
13440 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
13450 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
13460 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
13470 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
13480 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
13490 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
134a0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
134b0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
134c0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
134d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
134e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
134f0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  pe(sqlite3_stmt 
13500 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74  *, int i);.const
13510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
13520 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
13530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
13540 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
13550 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
13560 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
13570 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  t.**.** After an
13580 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
13590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20   SQL statement] 
135a0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
135b0 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a  d with a call.**
135c0 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69   to either [sqli
135d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
135e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
135f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
13600 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68   to one of.** th
13610 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
13620 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
13630 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
13640 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
13650 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66  ,.** then this f
13660 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
13670 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
13680 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
13690 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61  uate the .** sta
136a0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
136b0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
136c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
136d0 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  s sqlite3_step()
136e0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
136f0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
13700 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
13710 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
13720 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
13730 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
13740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
13750 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
13760 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
13770 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
13780 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
13790 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
137a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
137b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
137c0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
137d0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
137e0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
137f0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
13800 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
13810 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
13820 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
13830 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
13840 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
13850 68 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66  he lagacy interf
13860 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
13870 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
13880 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
13890 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  Y], .** [SQLITE_
138a0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
138b0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
138c0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
138d0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
138e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
138f0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
13900 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  other [SQLITE_OK
13910 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a   | result code].
13920 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
13930 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
13940 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
13950 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
13960 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a  ed as.** well..*
13970 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
13980 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
13990 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
139a0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
139b0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
139c0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
139d0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
139e0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
139f0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d  atement is a COM
13a00 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  MIT.** or occurs
13a10 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
13a20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
13a30 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
13a40 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
13a50 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
13a60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
13a70 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20  ot a COMMIT and 
13a80 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
13a90 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
13aa0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
13ab0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
13ac0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
13ad0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
13ae0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
13af0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
13b00 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
13b10 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
13b20 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
13b30 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
13b40 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
13b50 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
13b60 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
13b70 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
13b80 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
13b90 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
13ba0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
13bb0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
13bc0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
13bd0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
13be0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
13bf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13c00 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
13c10 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
13c20 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54   then .** [SQLIT
13c30 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e  E_ROW] is return
13c40 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
13c50 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
13c60 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70  s ready.** for p
13c70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
13c80 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
13c90 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
13ca0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  sed using.** the
13cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
13cc0 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63  _int | column ac
13cd0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
13ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
13cf0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
13d00 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
13d10 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
13d20 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c  ata..** .** [SQL
13d30 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
13d40 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
13d50 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
13d60 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
13d70 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
13d80 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
13d90 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
13da0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
13db0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
13dc0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
13dd0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
13de0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
13df0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
13e00 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
13e10 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
13e20 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
13e30 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65  or code (example
13e40 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  :.** [SQLITE_INT
13e50 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
13e60 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
13e70 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
13e80 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
13e90 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
13ea0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
13eb0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
13ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  .** [sqlite3_stm
13ed0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
13ee0 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
13ef0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
13f00 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
13f10 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
13f20 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
13f30 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
13f40 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
13f50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
13f60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
13f70 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
13f80 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
13f90 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
13fa0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
13fb0 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  on a [sqlite3_st
13fc0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
13fd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
13fe0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
13ff0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
14000 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
14010 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
14020 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  had .** previous
14030 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
14040 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
14050 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
14060 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
14070 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
14080 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
14090 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
140a0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
140b0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
140c0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
140d0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
140e0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
140f0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
14100 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  b>.** In the leg
14110 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a  acy interface, .
14120 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  ** the sqlite3_s
14130 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73  tep() API always
14140 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
14150 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a  ic error code,.*
14160 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
14170 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  , following any 
14180 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
14190 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
141a0 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  * and [SQLITE_MI
141b0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
141c0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72   call [sqlite3_r
141d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
141e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
141f0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
14200 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73  ind one of the s
14210 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49  pecific.** [SQLI
14220 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
14230 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  t codes] that be
14240 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
14250 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
14260 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
14270 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
14280 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
14290 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
142a0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
142b0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
142c0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
142d0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
142e0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
142f0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
14300 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
14310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14320 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
14330 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
14340 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
14350 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
14360 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
14370 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f   then the .** mo
14380 72 65 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c  re specific [SQL
14390 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75  ITE_ERROR | resu
143a0 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  lt codes] are re
143b0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
143c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
143d0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
143e0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
143f0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
14400 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
14410 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
14420 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
14430 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20  CAPI3REF:.**.** 
14440 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
14450 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
14460 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
14470 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
14480 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  ..**.** After a 
14490 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
144a0 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20 72 65  _step()] that re
144b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
144c0 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  W], this routine
144d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
144e0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
144f0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  s the [sqlite3_c
14500 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66  olumn_count()] f
14510 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65  unction..** Afte
14520 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
14530 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
14540 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  an [SQLITE_DONE]
14550 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
14560 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45   or.** a [SQLITE
14570 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63  _ERROR | error c
14580 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20  ode], or before 
14590 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
145a0 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61   has been .** ca
145b0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c  lled on the [sql
145c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
145d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
145e0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69  for the first ti
145f0 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  me,.** this rout
14600 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
14610 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
14620 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
14630 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
14640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14650 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
14660 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45  atatypes.**.** E
14670 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
14680 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
14690 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
146a0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
146b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
146c0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
146d0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
146e0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
146f0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
14700 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
14710 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
14720 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
14730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
14740 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
14750 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
14760 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
14770 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
14780 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
14790 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
147a0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
147b0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
147c0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
147d0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
147e0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
147f0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
14800 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
14810 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
14820 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
14830 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e  e SQLITE3_TEXT n
14840 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
14850 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
14860 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
14870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
14880 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
14890 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
148a0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
148b0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
148c0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
148d0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
148e0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
148f0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
14900 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
14910 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
14920 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
14930 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73  API3REF: Results
14940 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
14950 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  uery.**.** These
14960 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
14970 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
14980 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69  ut the informati
14990 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  on.** in a singl
149a0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
149b0 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
149c0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
149d0 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
149e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
149f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
14a00 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
14a10 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
14a20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
14a30 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
14a40 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c 69 74  uate (the [sqlit
14a50 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77  e3_stmt*] that w
14a60 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
14a70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
14a80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
14a90 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
14aa0 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73  ts) and.** the s
14ab0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
14ac0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
14ad0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
14ae0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ich information 
14af0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
14b00 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66  turned.  The lef
14b10 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 61  t-most column ha
14b20 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e  s an index of 0.
14b30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
14b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  L statement is n
14b50 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
14b60 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
14b70 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
14b80 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  the column index
14b90 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
14ba0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
14bb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
14bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
14bd0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
14be0 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
14bf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
14c00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
14c10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
14c20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
14c30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
14c40 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
14c50 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
14c60 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
14c70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
14c80 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
14c90 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
14ca0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
14cb0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
14cc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
14cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
14ce0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
14cf0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
14d00 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
14d10 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
14d20 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
14d30 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
14d40 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
14d50 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
14d60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
14d70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
14d80 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
14d90 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
14da0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
14db0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
14dc0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
14dd0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
14de0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
14df0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
14e00 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
14e10 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
14e20 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
14e30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
14e40 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
14e50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
14e60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14e70 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
14e80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
14e90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
14ea0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
14eb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
14ec0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
14ed0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
14ee0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
14ef0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
14f00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
14f10 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
14f20 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
14f30 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
14f40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
14f50 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
14f60 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
14f70 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
14f80 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
14f90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
14fa0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
14fb0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
14fc0 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
14fd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
14fe0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
14ff0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
15000 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
15010 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
15020 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
15030 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
15040 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
15050 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
15060 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
15070 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
15080 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
15090 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
150a0 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
150b0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
150c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
150d0 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
150e0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
150f0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65   in UTF-16 inste
15100 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a  ad of UTF-8.  .*
15110 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * The zero termi
15120 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
15130 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
15140 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  unt..**.** These
15150 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
15160 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
15170 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
15180 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
15190 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
151a0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
151b0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
151c0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
151d0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
151e0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
151f0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
15200 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
15210 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69   do the conversi
15220 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  on.** automatica
15230 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
15240 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
15250 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
15260 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70  s that.** are ap
15270 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
15280 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
15290 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
152a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
152b0 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 73  rnal <th> Reques
152c0 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 72  ted <th> .** <tr
152d0 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 3c  ><th>  Type    <
152e0 74 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c 74  th>    Type   <t
152f0 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  h> Conversion.**
15300 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
15310 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
15320 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
15330 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
15340 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
15350 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
15360 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
15370 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
15380 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
15390 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
153a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
153b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
153c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
153d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
153e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
153f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
15400 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
15410 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
15420 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
15430 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
15440 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
15450 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
15460 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
15470 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
15480 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
15490 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
154a0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
154b0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
154c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
154d0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
154e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
154f0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
15500 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
15510 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
15520 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
15530 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
15540 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
15550 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
15560 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
15570 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
15580 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
15590 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
155a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
155b0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
155c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
155d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
155e0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
155f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
15600 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
15610 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
15620 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
15630 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
15640 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
15650 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
15660 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
15670 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
15680 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
15690 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
156a0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
156b0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
156c0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
156d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
156e0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
156f0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
15700 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
15710 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15720 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
15730 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
15740 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
15750 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
15760 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
15770 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
15780 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
15790 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
157a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
157b0 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e  .** on equavalen
157c0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
157d0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
157e0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
157f0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
15800 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
15810 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
15820 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
15830 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
15840 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
15850 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
15860 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
15870 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
15880 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
15890 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
158a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
158b0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
158c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
158d0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
158e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
158f0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
15900 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20  dated. .** Type 
15910 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
15920 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
15930 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
15940 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
15950 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
15960 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c  ** <ul>.** <li><
15970 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
15980 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
15990 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
159a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20  lumn_text() .** 
159b0 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69           or sqli
159c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
159d0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
159e0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
159f0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
15a00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
15a10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
15a20 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  ng.</p></li>.**.
15a30 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
15a40 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
15a50 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
15a60 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
15a70 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
15a80 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
15a90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
15aa0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
15ab0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
15ac0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
15ad0 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31          to UTF-1
15ae0 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  6.</p></li>.**.*
15af0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
15b00 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
15b10 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
15b20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
15b30 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
15b40 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
15b50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
15b60 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
15b70 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
15b80 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
15b90 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70      to UTF-8.</p
15ba0 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ></li>.** </ul>.
15bb0 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
15bc0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
15bd0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
15be0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
15bf0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
15c00 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
15c10 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
15c20 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
15c30 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
15c40 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
15c50 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
15c60 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
15c70 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
15c80 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
15c90 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
15ca0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
15cb0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
15cc0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
15cd0 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20  but sometime it 
15ce0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
15cf0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
15d00 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
15d10 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
15d20 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ated.  .**.** Th
15d30 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
15d40 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
15d50 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
15d60 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
15d70 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
15d80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
15d90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e  ays:.**.**  <ul>
15da0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
15db0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
15dc0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
15dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
15de0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
15df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
15e00 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
15e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
15e20 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
15e30 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
15e40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
15e50 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
15e60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
15e70 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e  )</li>.**  </ul>
15e80 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
15e90 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
15ea0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
15eb0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71  olumn_text(), sq
15ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
15ed0 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  b(),.** or sqlit
15ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
15ef0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
15f00 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  e the result int
15f10 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a  o the desired.**
15f20 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
15f30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
15f40 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73  umn_bytes() or s
15f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
15f60 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69  tes16() to.** fi
15f70 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
15f80 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
15f90 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73  ot mix call to s
15fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
15fb0 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  xt() or.** sqlit
15fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
15fd0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
15fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
15ff0 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f  tes16().  And do
16000 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c   not.** mix call
16010 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
16020 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74  umn_text16() wit
16030 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
16040 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
16050 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )..*/.const void
16060 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
16070 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
16080 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
16090 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
160a0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
160b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
160c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
160d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
160e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
160f0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
16100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
16110 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
16120 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
16130 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
16140 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
16150 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
16160 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
16180 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
16190 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
161a0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
161b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
161c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
161d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
161e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
161f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
16200 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
16210 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
16220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16230 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
16240 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
16250 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
16260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
16270 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
16280 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
16290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
162a0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
162b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
162c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
162d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
162e0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
162f0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a   to delete a .**
16300 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c   [sqlite3_stmt |
16310 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74   compiled SQL st
16320 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65  atement]. If the
16330 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
16340 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  * executed succe
16350 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20  ssfully, or not 
16360 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
16370 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20   then SQLITE_OK 
16380 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
16390 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
163a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
163b0 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a  iled then an .**
163c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c   [SQLITE_ERROR |
163d0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20   error code] or 
163e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
163f0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72  AD | extended er
16400 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
16410 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  returned. .**.**
16420 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
16430 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
16440 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
16450 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
16460 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16470 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20  _stmt | virtual 
16480 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68  machine].  If th
16490 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
164a0 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f  e has not .** co
164b0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
164c0 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
164d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
164e0 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
164f0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
16500 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
16510 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c  rupt.  (See [sql
16520 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16530 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  ].) .** Incomple
16540 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
16550 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
16560 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
16570 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64  ancelled,  .** d
16580 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
16590 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
165a0 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  nd the .** [SQLI
165b0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c  TE_ERROR | resul
165c0 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  t code] returned
165d0 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
165e0 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  _ABORT]..*/.int 
165f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
16600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
16610 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
16620 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
16630 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
16640 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
16650 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
16660 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
16670 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
16680 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  a .** [sqlite3_s
16690 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
166a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  QL statement] ob
166b0 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f  ject..** back to
166c0 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74   it's initial st
166d0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
166e0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
166f0 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
16700 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
16710 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
16720 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
16730 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
16740 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
16750 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
16760 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
16770 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
16780 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
16790 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
167a0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
167b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
167c0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
167d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
167e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
167f0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
16800 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
16810 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
16820 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
16830 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
16840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
16850 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f   aggregates.** o
16860 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
16870 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78  e behavior of ex
16880 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
16890 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
168a0 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66  es.  The.** diff
168b0 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77  erence only betw
168c0 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74  een the two is t
168d0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70  hat the second p
168e0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a  arameter, the.**
168f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
16900 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
16910 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  r aggregate, is 
16920 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
16930 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
16940 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
16950 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72  ) and UTF-16 for
16960 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
16970 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  function16()..**
16980 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16990 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73  gument is the [s
169a0 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73  qlite3 | databas
169b0 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68  e handle] that h
169c0 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20  olds the.** SQL 
169d0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
169e0 65 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61  egate is to be a
169f0 64 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65  dded or redefine
16a00 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a  d. If a single.*
16a10 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  * program uses m
16a20 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
16a30 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74  abase handle int
16a40 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
16a50 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f  L.** functions o
16a60 72 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73  r aggregates mus
16a70 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
16a80 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
16a90 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64  database.** hand
16aa0 6c 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68  le with which th
16ab0 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e  ey will be used.
16ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
16ad0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
16ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
16af0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
16b00 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20  e created.** or 
16b10 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  redefined..** Th
16b20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
16b30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
16b40 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
16b50 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a  clusive of the .
16b60 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ** zero-terminat
16b70 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
16b80 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
16b90 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
16ba0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
16bb0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
16bc0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
16bd0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
16be0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
16bf0 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53  l result in an S
16c00 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f  QLITE_ERROR erro
16c10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  r..**.** The thi
16c20 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
16c30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
16c40 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
16c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
16c60 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
16c70 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
16c80 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
16c90 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
16ca0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
16cb0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
16cc0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
16cd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
16ce0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
16cf0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
16d00 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
16d10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
16d20 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
16d30 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
16d40 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
16d50 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
16d60 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
16d70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
16d80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
16d90 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
16da0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
16db0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
16dc0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
16dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
16de0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
16df0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
16e00 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
16e10 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
16e20 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
16e30 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
16e40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
16e50 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
16e60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
16e70 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
16e80 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
16e90 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
16ea0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
16eb0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
16ec0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
16ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
16ee0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
16ef0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
16f00 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
16f10 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
16f20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
16f30 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
16f40 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
16f50 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
16f60 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
16f70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
16f80 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
16f90 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20  re what.** text 
16fa0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
16fb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
16fc0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
16fd0 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  d be.** [SQLITE_
16fe0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
16ff0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
17000 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
17010 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
17020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
17030 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
17040 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
17050 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
17060 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
17070 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
17080 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
17090 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
170a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
170b0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
170c0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
170d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
170e0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
170f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
17100 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
17110 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
17120 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
17130 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
17140 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
17150 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75  on of.** the xFu
17160 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  nc callback only
17170 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
17180 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
17190 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a   as the xStep.**
171a0 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61   and xFinal para
171b0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
171c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
171d0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
171e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
171f0 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  of xStep and xFi
17200 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
17210 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
17220 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
17230 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e  te an.** existin
17240 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  g SQL function o
17250 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
17260 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
17270 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
17280 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
17290 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
172a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
172b0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
172c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
172d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
172e0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
172f0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
17300 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
17310 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
17320 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
17330 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20   perferred text 
17340 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
17350 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
17360 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
17370 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
17380 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
17390 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
173a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
173b0 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
173c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
173d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
173e0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
173f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
17400 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
17410 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
17420 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  d*,.  void (*xFu
17430 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
17440 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
17450 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
17460 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
17470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
17480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
17490 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
174a0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
174b0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
174c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
174d0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
174e0 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  *,.  const void 
174f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
17500 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
17510 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
17520 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  id*,.  void (*xF
17530 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
17540 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
17550 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
17560 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
17570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
17580 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
17590 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
175a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
175b0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
175c0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
175d0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
175e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
175f0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
17600 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
17610 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
17620 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
17630 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
17640 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
17650 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
17660 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
17670 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
17680 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
17690 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
176a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
176b0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
176c0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
176d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
176e0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
176f0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
17700 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
17710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
17720 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
17730 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
17740 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
17750 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
17760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
17770 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17780 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75  REF: Obsolete Fu
17790 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
177a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
177b0 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65  e all now obsole
177c0 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  te.  In order to
177d0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
177e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
177f0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
17800 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75  code, we continu
17810 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20  e to support.** 
17820 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
17830 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64    However, new d
17840 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65  evelopment proje
17850 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  cts should avoid
17860 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
17870 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
17880 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
17890 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
178a0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
178b0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
178c0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
178d0 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
178e0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  hey do..*/.int s
178f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
17900 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
17910 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71  ontext*);.int sq
17920 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
17930 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
17940 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
17950 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
17960 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
17970 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
17980 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
17990 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69  cover(void);.voi
179a0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
179b0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
179c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
179d0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
179e0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
179f0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
17a00 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
17a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
17a20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
17a30 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
17a40 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
17a50 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
17a60 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
17a70 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
17a80 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
17a90 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
17aa0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
17ab0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
17ac0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
17ad0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
17ae0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
17af0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
17b00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
17b10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
17b20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
17b30 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
17b40 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
17b50 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
17b60 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
17b70 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
17b80 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
17b90 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
17ba0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
17bb0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
17bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
17bd0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
17be0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
17bf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
17c00 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
17c10 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
17c20 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
17c30 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
17c40 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
17c50 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
17c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
17c70 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
17c80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
17c90 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
17ca0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
17cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
17cc0 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
17cd0 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
17ce0 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
17cf0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
17d00 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
17d10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
17d20 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  ] pointer instea
17d30 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  d.** of an [sqli
17d40 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
17d50 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
17d60 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
17d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17d80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
17d90 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
17da0 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
17db0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
17dc0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
17dd0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
17de0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
17df0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
17e00 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
17e10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
17e20 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
17e30 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
17e40 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
17e50 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
17e60 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
17e70 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
17e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
17e90 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
17ea0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
17eb0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
17ec0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
17ed0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
17ee0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
17ef0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
17f00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
17f10 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
17f20 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
17f30 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
17f40 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
17f50 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
17f60 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
17f70 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65  rmation (in orde
17f80 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
17f90 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69 67 69  e value is origi
17fa0 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74 68 61  nal a string tha
17fb0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
17fc0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69  umber).** then i
17fd0 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65  t is done.  Othe
17fe0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
17ff0 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ion occurs.  The
18000 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54   .** [SQLITE_INT
18010 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
18020 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
18030 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
18040 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
18050 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
18060 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
18070 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
18080 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74  r that.** is ret
18090 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
180a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
180b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
180c0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
180d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
180e0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
180f0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
18100 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
18110 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
18120 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
18130 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
18140 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
18150 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
18160 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
18170 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
18180 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  )].  .**.** Thes
18190 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
181a0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
181b0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
181c0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
181d0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
181e0 69 65 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ied the sqlite3_
181f0 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72  value* parameter
18200 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
18210 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
18220 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
18230 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
18240 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
18250 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
18260 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
18270 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
18280 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
18290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
182a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
182b0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
182c0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
182d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
182e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
182f0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
18300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
18310 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
18320 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
18330 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
18340 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
18350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
18360 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
18370 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
18380 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
18390 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
183a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
183b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
183c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
183d0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
183e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
183f0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
18400 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
18410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
18420 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
18430 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
18440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
18450 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
18460 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
18470 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
18480 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
18490 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
184a0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
184b0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
184c0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
184d0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
184e0 20 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72   state.  The fir
184f0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
18500 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  tine.** is calle
18510 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  d for a particul
18520 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20  ar aggregate, a 
18530 6e 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66  new structure of
18540 20 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20   size nBytes.** 
18550 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65  is allocated, ze
18560 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e  roed, and return
18570 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65  ed.  On subseque
18580 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68  nt calls (for th
18590 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67  e.** same aggreg
185a0 61 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68  ate instance) th
185b0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
185c0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
185d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
185e0 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
185f0 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
18600 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
18610 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
18620 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66  a..**.** The buf
18630 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73  fer allocated is
18640 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
18650 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77  ally by SQLite w
18660 68 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  han the aggregat
18670 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
18680 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
18690 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
186a0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
186b0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
186c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
186d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
186e0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
186f0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
18700 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
18710 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
18720 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
18730 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
18740 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
18750 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
18760 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
18770 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
18780 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
18790 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
187a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
187b0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
187c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
187d0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
187e0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
187f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18800 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
18810 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
18820 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20  * The pUserData 
18830 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18840 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
18850 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
18860 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
18870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
18880 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  ] routines.** us
18890 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75  ed to register u
188a0 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73  ser functions is
188b0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a   available to.**
188c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
188d0 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ion of the funct
188e0 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63  ion using this c
188f0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  all..**.** This 
18900 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
18910 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
18920 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
18930 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
18940 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 6f 72 69  function was ori
18950 67 69 6e 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 2e  ginally invoked.
18960 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
18970 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
18980 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
18990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
189a0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
189b0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
189c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
189d0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
189e0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
189f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
18a00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
18a10 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67  ta-data with arg
18a20 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
18a30 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
18a40 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
18a50 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
18a60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
18a70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
18a80 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
18a90 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
18aa0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
18ab0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
18ac0 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62   meta-data may b
18ad0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
18ae0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
18af0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
18b00 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
18b10 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
18b20 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
18b30 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
18b40 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
18b50 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
18b60 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
18b70 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61   as.** meta-data
18b80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
18b90 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
18ba0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
18bb0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
18bc0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
18bd0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
18be0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
18bf0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
18c00 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
18c10 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
18c20 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
18c30 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
18c40 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
18c50 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
18c60 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
18c70 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
18c80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
18c90 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
18ca0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
18cb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
18cc0 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74   to the meta-dat
18cd0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
18ce0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
18cf0 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f 20 74  ument value to t
18d00 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 66  he current SQL f
18d10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c  unction.** call,
18d20 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
18d30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18d40 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74  . If no meta-dat
18d50 61 20 68 61 73 20 62 65 65 6e 20 73 65 74 20 66  a has been set f
18d60 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c 75 65  or.** that value
18d70 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
18d80 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
18d90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
18da0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
18db0 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 61 73  () is used to as
18dc0 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74  sociate meta-dat
18dd0 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a  a with an SQL.**
18de0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
18df0 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20 70 61  nt. The third pa
18e00 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18e10 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
18e20 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61  -data.** to be a
18e30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
18e40 68 65 20 4e 74 68 20 75 73 65 72 20 66 75 6e 63  he Nth user func
18e50 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20 76 61  tion argument va
18e60 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74 68 0a  lue. The fourth.
18e70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 70 65  ** parameter spe
18e80 63 69 66 69 65 73 20 61 20 64 65 73 74 72 75 63  cifies a destruc
18e90 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tor that will be
18ea0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d   called on the m
18eb0 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69  eta-.** data poi
18ec0 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73 65 20  nter to release 
18ed0 69 74 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  it when it is no
18ee0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
18ef0 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64 65 73  . If the .** des
18f00 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c  tructor is NULL,
18f10 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b   it is not invok
18f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
18f30 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
18f40 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
18f50 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
18f60 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
18f70 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
18f80 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
18f90 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
18fa0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
18fb0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
18fc0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
18fd0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18fe0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
18ff0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
19000 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
19010 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
19020 6f 6e 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c  on was originall
19030 79 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2f 0a 76 6f  y invoked..*/.vo
19040 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
19050 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
19060 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
19070 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
19080 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
19090 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c 20  _context*, int, 
190a0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
190b0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
190c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
190d0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
190e0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
190f0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
19100 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
19110 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
19120 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
19130 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
19140 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
19150 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
19160 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
19170 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
19180 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
19190 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
191a0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
191b0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
191c0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
191d0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
191e0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
191f0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
19200 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
19210 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
19220 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
19230 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
19240 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
19250 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
19260 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
19270 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
19280 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
19290 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
192a0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
192b0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
192c0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
192d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
192e0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
192f0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
19300 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
19310 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
19320 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
19330 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
19340 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
19350 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
19360 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
19370 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
19380 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
19390 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
193a0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
193b0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
193c0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
193d0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
193e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
193f0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
19400 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
19410 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
19420 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
19430 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
19440 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
19450 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
19460 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
19470 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
19480 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
19490 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
194a0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
194b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
194c0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
194d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
194e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
194f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
19500 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
19510 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
19520 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
19530 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61  lite3_bind_*] fa
19540 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
19550 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e  s used.** to bin
19560 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
19570 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
19580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19590 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
195a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
195b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
195c0 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d  te3_bind_* docum
195d0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a  entation] for.**
195e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
195f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
19600 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
19610 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
19620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
19630 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
19640 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
19650 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
19660 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
19670 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20 54  an exception.  T
19680 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  he.** parameter 
19690 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
196a0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
196b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
196c0 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65 20  r16().** is the 
196d0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
196e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
196f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
19700 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75 73  lt_toobig() caus
19710 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  e the function i
19720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
19730 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65 72   to throw and er
19740 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
19750 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
19760 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a  BLOB is to long.
19770 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ** to represent.
19780 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19790 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
197a0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
197b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
197c0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
197d0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
197e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ed with the [sql
197f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
19800 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73  inter..*/.void s
19810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
19820 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
19830 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
19840 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
19850 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
19860 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
19870 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
19880 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
19890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
198a0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
198b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
198c0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
198d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
198e0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
198f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
19900 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
19910 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
19920 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
19930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
19940 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
19950 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
19960 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
19970 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
19980 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
19990 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
199a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
199b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
199c0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
199d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
199e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
199f0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
19a00 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
19a10 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
19a20 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
19a30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
19a40 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
19a50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
19a60 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
19a70 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
19a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
19a90 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
19aa0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
19ab0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
19ac0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
19ad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
19ae0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
19af0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
19b00 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
19b10 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
19b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
19b30 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
19b40 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
19b50 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
19b60 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
19b70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
19b80 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
19b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
19ba0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
19bb0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
19bc0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
19bd0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
19be0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
19bf0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
19c00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d  he.** [sqlite3*]
19c10 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65   handle specifie
19c20 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
19c30 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20  rgument. .**.** 
19c40 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
19c50 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
19c60 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
19c70 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
19c80 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
19c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
19ca0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
19cb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
19cc0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
19cd0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
19ce0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
19cf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
19d00 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  ).  In all cases
19d10 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
19d20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
19d30 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
19d40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
19d50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
19d60 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
19d70 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
19d80 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
19d90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
19da0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
19db0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
19dc0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
19dd0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
19de0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
19df0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
19e00 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
19e10 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
19e20 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
19e30 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
19e40 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
19e50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
19e60 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
19e70 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
19e80 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
19e90 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
19ea0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
19eb0 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
19ec0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
19ed0 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
19ee0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
19ef0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
19f00 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
19f10 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
19f20 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75   Each time the u
19f30 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ser.** supplied 
19f40 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
19f50 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
19f60 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
19f70 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
19f80 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
19f90 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19fa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
19fb0 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
19fc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
19fd0 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
19fe0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
19ff0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
1a000 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
1a010 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
1a020 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
1a030 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
1a040 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
1a050 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61  by a [length, da
1a060 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta] pair and enc
1a070 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
1a080 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
1a090 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
1a0a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
1a0b0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
1a0c0 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
1a0d0 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65   registered. The
1a0e0 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68   user routine sh
1a0f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61  ould return nega
1a100 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
1a110 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65  sitive if.** the
1a120 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
1a130 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
1a140 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
1a150 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
1a160 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  .** string. i.e.
1a170 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
1a180 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
1a190 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1a1a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
1a1b0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1a1c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1a1d0 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68  n().** excapt th
1a1e0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
1a1f0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
1a200 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
1a210 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
1a220 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
1a230 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
1a240 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
1a250 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
1a260 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
1a270 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
1a280 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1a290 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
1a2a0 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
1a2b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1a2c0 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c  tion_v2().  Coll
1a2d0 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
1a2e0 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65  oyed when.** the
1a2f0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
1a300 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
1a310 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
1a320 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
1a330 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ons.** or when t
1a340 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
1a350 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73  tabase handle is
1a360 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
1a370 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
1a380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a390 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1a3a0 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ion_v2() interfa
1a3b0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
1a3c0 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63  al and.** subjec
1a3d0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1a3e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
1a3f0 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61   The other colla
1a400 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a  tion creation.**
1a410 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73   functions are s
1a420 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  table..*/.int sq
1a430 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1a440 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
1a450 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1a460 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1a470 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1a480 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1a490 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1a4a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1a4b0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1a4c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1a4d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
1a4e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
1a4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1a500 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
1a510 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
1a520 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
1a530 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1a540 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
1a550 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
1a560 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
1a570 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1a580 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
1a590 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
1a5a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
1a5b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
1a5c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
1a5d0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
1a5e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1a5f0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
1a600 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
1a610 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
1a620 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
1a630 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20  lbacks.**.** To 
1a640 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
1a650 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
1a660 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
1a670 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
1a680 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
1a690 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
1a6a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
1a6b0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
1a6c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61  with the.** data
1a6d0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62  base handle to b
1a6e0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
1a6f0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
1a700 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
1a710 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64  e is.** required
1a720 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1a730 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
1a740 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
1a750 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1a760 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
1a770 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
1a780 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
1a790 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
1a7a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
1a7b0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
1a7c0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
1a7d0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
1a7e0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
1a7f0 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
1a800 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
1a810 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
1a820 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
1a830 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20  e order. A call 
1a840 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
1a850 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
1a860 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
1a870 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
1a880 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1a890 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
1a8a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
1a8b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
1a8c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
1a8d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1a8e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
1a8f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
1a900 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1a910 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65  eded16(). The se
1a920 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1a930 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1a940 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69   handle. The thi
1a950 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
1a960 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
1a970 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
1a980 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51  16BE], or.** [SQ
1a990 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
1a9a0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
1a9b0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
1a9c0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
1a9d0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
1a9e0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
1a9f0 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
1aa00 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
1aa10 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
1aa20 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
1aa30 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
1aa40 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1aa50 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
1aa60 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
1aa70 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
1aa80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
1aa90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
1aaa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
1aab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1aac0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
1aad0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
1aae0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
1aaf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1ab00 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
1ab10 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
1ab20 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
1ab30 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
1ab40 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
1ab50 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
1ab60 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
1ab70 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
1ab80 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
1ab90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
1aba0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
1abb0 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
1abc0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
1abd0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
1abe0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
1abf0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
1ac00 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
1ac10 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
1ac20 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
1ac30 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
1ac40 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
1ac50 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
1ac60 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
1ac70 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
1ac80 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
1ac90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
1aca0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1acb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1acc0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
1acd0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
1ace0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
1acf0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
1ad00 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
1ad10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
1ad20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
1ad30 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
1ad40 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
1ad50 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
1ad60 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
1ad70 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
1ad80 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
1ad90 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
1ada0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1adb0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
1adc0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
1add0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
1ade0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
1adf0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
1ae00 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
1ae10 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
1ae20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
1ae30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ae40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ae50 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
1ae60 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
1ae70 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
1ae80 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
1ae90 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
1aea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aeb0 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
1aec0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
1aed0 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
1aee0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1aef0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
1af00 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
1af10 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20   execution.** a 
1af20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
1af30 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
1af40 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
1af50 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
1af60 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1af70 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
1af80 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
1af90 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73   with .** millis
1afa0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
1afb0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
1afc0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
1afd0 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74  nded up to .** t
1afe0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
1aff0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
1b000 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1b010 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
1b020 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
1b030 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
1b040 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
1b050 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
1b060 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
1b070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b080 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f    Name Of The Fo
1b090 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
1b0a0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
1b0b0 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
1b0c0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
1b0d0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
1b0e0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
1b0f0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
1b100 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20  a folder (a.ka. 
1b110 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
1b120 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
1b130 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
1b140 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
1b150 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
1b160 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
1b170 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
1b180 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
1b190 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f  , then SQLite do
1b1a0 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  es a search for 
1b1b0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  an appropriate t
1b1c0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65  emporary.** file
1b1d0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
1b1e0 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f  * Once [sqlite3_
1b1f0 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e  open()] has been
1b200 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e   called, changin
1b210 67 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  g this variable 
1b220 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61  will.** invalida
1b230 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  te the current t
1b240 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73  emporary databas
1b250 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65  e, if any.  Gene
1b260 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a  rally speaking,.
1b270 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  ** it is not saf
1b280 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73  e to invoke this
1b290 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b   routine after [
1b2a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1b2b0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c  has.** been call
1b2c0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
1b2d0 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
1b2e0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
1b2f0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
1b300 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65  EF:  Test To See
1b310 20 49 66 20 54 68 65 20 44 61 74 61 62 73 65 20   If The Databse 
1b320 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
1b330 74 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73  t Mode.**.** Tes
1b340 74 20 74 6f 20 73 65 65 20 77 68 65 74 68 65 72  t to see whether
1b350 20 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61   or not the data
1b360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b370 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  is in autocommit
1b380 0a 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72  .** mode.  Retur
1b390 6e 20 54 52 55 45 20 69 66 20 69 74 20 69 73 20  n TRUE if it is 
1b3a0 61 6e 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74  and FALSE if not
1b3b0 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  .  Autocommit mo
1b3c0 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64  de is on.** by d
1b3d0 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d  efault.  Autocom
1b3e0 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 20  mit is disabled 
1b3f0 62 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65  by a BEGIN state
1b400 6d 65 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c  ment and reenabl
1b410 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78  ed.** by the nex
1b420 74 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c  t COMMIT or ROLL
1b430 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  BACK..**.** If a
1b440 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
1b450 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
1b460 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
1b470 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1b480 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
1b490 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1b4a0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
1b4b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
1b4c0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
1b4d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
1b4e0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
1b4f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b500 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
1b510 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
1b520 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57  dle Associated W
1b530 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53  ith A Prepared S
1b540 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52  tatement.**.** R
1b550 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74  eturn the [sqlit
1b560 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
1b570 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
1b580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
1b590 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
1b5a0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
1b5b0 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73  ** This is the s
1b5c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
1b5d0 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
1b5e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1b5f0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
1b600 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b610 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1b620 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
1b630 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
1b640 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1b650 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
1b660 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
1b670 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
1b680 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a  te3_stmt*);.../*
1b690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1b6a0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
1b6b0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
1b6c0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
1b6d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
1b6e0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1b6f0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ck functions to 
1b700 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1b710 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
1b720 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65  n.** is committe
1b730 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b  d or rolled back
1b740 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75  .  The pArg argu
1b750 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
1b760 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
1b770 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
1b780 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
1b790 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
1b7a0 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
1b7b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1b7c0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
1b7d0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
1b7e0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
1b7f0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
1b800 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
1b810 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
1b820 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ts pArg value is
1b830 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74   returned..** Ot
1b840 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
1b850 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1b860 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
1b870 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
1b880 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
1b890 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
1b8a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
1b8b0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
1b8c0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
1b8d0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
1b8e0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
1b8f0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
1b900 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
1b910 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
1b920 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
1b930 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
1b940 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
1b950 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68  ack to occur. Th
1b960 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  e .** callback i
1b970 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
1b980 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
1b990 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
1b9a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62  rolled.** back b
1b9b0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
1b9c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1b9d0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1b9e0 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
1b9f0 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
1ba00 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
1ba10 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  t to change..*/.
1ba20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1ba30 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
1ba40 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
1ba50 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
1ba60 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
1ba70 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
1ba80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
1ba90 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1baa0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
1bab0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
1bac0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1bad0 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63  .** Register a c
1bae0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1baf0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
1bb00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
1bb10 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1bb20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
1bb30 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
1bb40 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
1bb50 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
1bb60 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
1bb70 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
1bb80 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
1bb90 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1bba0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
1bbb0 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
1bbc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1bbd0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
1bbe0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1bbf0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
1bc00 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
1bc10 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
1bc20 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
1bc30 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
1bc40 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68  d or deleted. Th
1bc50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1bc60 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1bc70 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
1bc80 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1bc90 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
1bca0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68  pdate_hook(). Th
1bcb0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
1bcc0 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
1bcd0 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f  s one of SQLITE_
1bce0 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44  INSERT, SQLITE_D
1bcf0 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f  ELETE or SQLITE_
1bd00 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e  UPDATE, dependin
1bd10 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72  g.** on the oper
1bd20 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
1bd30 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
1bd40 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68  o be invoked. Th
1bd50 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
1bd60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
1bd70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1bd80 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
1bd90 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
1bda0 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
1bdb0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
1bdc0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
1bdd0 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  . The final call
1bde0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
1bdf0 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
1be00 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74  of the row. In t
1be10 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
1be20 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
1be30 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
1be40 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
1be50 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
1be60 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
1be70 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
1be80 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
1be90 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
1bea0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
1beb0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
1bec0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
1bed0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
1bee0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
1bef0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
1bf00 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
1bf10 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
1bf20 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
1bf30 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
1bf40 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ned..*/.void *sq
1bf50 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
1bf60 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
1bf70 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
1bf80 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
1bf90 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
1bfa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
1bfb0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
1bfc0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
1bfd0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
1bfe0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
1bff0 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
1c000 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
1c010 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
1c020 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
1c030 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
1c040 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
1c050 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
1c060 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
1c070 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1c080 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
1c090 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1c0a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
1c0b0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
1c0c0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
1c0d0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
1c0e0 20 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51   Beginning in SQ
1c0f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1c100 2e 30 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e  .0, cache sharin
1c110 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
1c120 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72   disabled.** for
1c130 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
1c140 73 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65  ss.  In prior ve
1c150 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1c160 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a  , sharing was.**
1c170 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
1c180 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
1c190 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
1c1a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
1c1b0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
1c1c0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
1c1d0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
1c1e0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
1c1f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c200 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1c210 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
1c220 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
1c230 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
1c240 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
1c250 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
1c260 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
1c270 6d 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a  mode that was.**
1c280 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
1c290 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
1c2a0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
1c2b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
1c2c0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
1c2d0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
1c2e0 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
1c2f0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1c300 65 64 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ed, the sqlite3_
1c310 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
1c320 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
1c330 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
1c340 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
1c350 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
1c360 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
1c370 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
1c380 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
1c390 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
1c3a0 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
1c3b0 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
1c3c0 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f  ly.  An [SQLITE_
1c3d0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
1c3e0 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
1c3f0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
1c400 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
1c410 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1c420 64 65 66 61 75 6c 74 20 66 6f 72 20 62 61 63 6b  default for back
1c430 77 61 72 64 20 63 6f 6d 70 61 74 69 62 69 6c 69  ward compatibili
1c440 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
1c450 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1c460 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
1c470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41  .** CAPI3REF:  A
1c480 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
1c490 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
1c4a0 20 41 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   Attempt to free
1c4b0 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70   N bytes of heap
1c4c0 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
1c4d0 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
1c4e0 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ntial.** memory 
1c4f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64  allocations held
1c500 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
1c510 20 6c 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c   library (exampl
1c520 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73  e: memory .** us
1c530 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
1c540 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
1c550 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
1c560 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  e)..**.** This f
1c570 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  unction is not a
1c580 20 70 61 72 74 20 6f 66 20 73 74 61 6e 64 61 72   part of standar
1c590 64 20 62 75 69 6c 64 73 2e 20 20 49 74 20 69 73  d builds.  It is
1c5a0 20 6f 6e 6c 79 20 63 72 65 61 74 65 64 0a 2a 2a   only created.**
1c5b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
1c5c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
1c5d0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
1c5e0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20  MORY_MANAGEMENT 
1c5f0 6d 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  macro..*/.int sq
1c600 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
1c610 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
1c620 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70  * CAPI3REF:  Imp
1c630 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
1c640 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50  eap Size.**.** P
1c650 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20 6c 69  lace a "soft" li
1c660 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  mit on the amoun
1c670 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
1c680 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
1c690 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c  ocated.** by SQL
1c6a0 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e 74 65  ite.  If an inte
1c6b0 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
1c6c0 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
1c6d0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
1c6e0 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ed the specified
1c6f0 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
1c700 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1c710 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  )] is.** invoked
1c720 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1c730 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
1c740 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
1c750 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
1c760 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a  * is made..**.**
1c770 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
1c780 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
1c790 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33  ause if [sqlite3
1c7a0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
1c7b0 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65  )] cannot.** fre
1c7c0 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  e sufficient mem
1c7d0 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74  ory to prevent t
1c7e0 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65  he limit from be
1c7f0 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a  ing exceeded,.**
1c800 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61   the memory is a
1c810 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20  llocated anyway 
1c820 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
1c830 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1c840 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61  ds..**.** A nega
1c850 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c  tive or zero val
1c860 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74  ue for N means t
1c870 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
1c880 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
1c890 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1c8a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
1c8b0 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  ] will only be c
1c8c0 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
1c8d0 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  y is exhausted..
1c8e0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
1c8f0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
1c900 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
1c910 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
1c920 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
1c930 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
1c940 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1c950 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a  mit.  But if it.
1c960 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  ** is unable to 
1c970 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
1c980 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  age below the so
1c990 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74  ft limit, execut
1c9a0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
1c9b0 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
1c9c0 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
1c9d0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
1c9e0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
1c9f0 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
1ca00 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
1ca10 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
1ca20 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1ca30 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1ca40 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
1ca50 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
1ca60 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
1ca70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
1ca80 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
1ca90 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1caa0 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
1cab0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
1cac0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
1cad0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1cae0 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
1caf0 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
1cb00 70 6c 69 65 64 20 63 75 6d 75 6c 61 74 69 76 65  plied cumulative
1cb10 6c 79 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ly to all thread
1cb20 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1cb30 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
1cb40 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  it(int);../*.** 
1cb50 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61  CAPI3REF:  Extra
1cb60 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
1cb70 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
1cb80 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73  Table.**.** This
1cb90 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75   routine.** retu
1cba0 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62  rns meta-data ab
1cbb0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
1cbc0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
1cbd0 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  fic database.** 
1cbe0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
1cbf0 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65   using the conne
1cc00 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73  ction handle pas
1cc10 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
1cc20 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72   function .** ar
1cc30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
1cc40 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
1cc50 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
1cc60 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
1cc70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1cc80 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75  s to .** this fu
1cc90 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f  nction. The seco
1cca0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1ccb0 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
1ccc0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1ccd0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
1cce0 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74   "temp" or an at
1ccf0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
1cd00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
1cd10 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
1cd20 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69  le or NULL. If i
1cd30 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
1cd40 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74  all attached dat
1cd50 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63  abases are searc
1cd60 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74  hed.** for the t
1cd70 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73  able using the s
1cd80 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73  ame algorithm as
1cd90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
1cda0 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a  gine uses to .**
1cdb0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
1cdc0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
1cdd0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ences..**.** The
1cde0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
1cdf0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1ce00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72  this function ar
1ce10 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20  e the table and 
1ce20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20  column .** name 
1ce30 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
1ce40 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
1ce50 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
1ce60 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
1ce70 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c   .** may be NULL
1ce80 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66  ..**.** Meta inf
1ce90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75  ormation is retu
1cea0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
1ceb0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
1cec0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
1ced0 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64  s.** the 5th and
1cee0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
1cef0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
1cf00 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20  unction. Any of 
1cf10 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65  these .** argume
1cf20 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c  nts may be NULL,
1cf30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1cf40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1cf50 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
1cf60 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   .** information
1cf70 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a   is ommitted..**
1cf80 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72  .** <pre>.** Par
1cf90 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 75  ameter     Outpu
1cfa0 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73 63  t Type      Desc
1cfb0 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d  ription.** -----
1cfc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cfd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1cfe0 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20  *.**   5th      
1cff0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
1d000 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a      Data type.**
1d010 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20 63     6th         c
1d020 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
1d030 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61  Name of the defa
1d040 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
1d050 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68  quence .**   7th
1d060 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
1d070 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
1d080 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73  f the column has
1d090 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
1d0a0 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20  traint.**   8th 
1d0b0 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
1d0c0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
1d0d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70   the column is p
1d0e0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
1d0f0 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20  RY KEY.**   9th 
1d100 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
1d110 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
1d120 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41   the column is A
1d130 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20  UTOINCREMENT.** 
1d140 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20  </pre>.**.**.** 
1d150 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
1d160 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
1d170 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
1d180 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
1d190 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e   .** declaration
1d1a0 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
1d1b0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
1d1c0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
1d1d0 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61   the next .** ca
1d1e0 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65  ll to any sqlite
1d1f0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
1d200 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
1d210 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
1d220 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
1d230 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73  then an error is
1d240 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1d250 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
1d260 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
1d270 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
1d280 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a  rowid_" and an .
1d290 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  ** INTEGER PRIMA
1d2a0 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61  RY KEY column ha
1d2b0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
1d2c0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
1d2d0 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20   the output .** 
1d2e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
1d2f0 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
1d300 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
1d310 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20  olumn. If there 
1d320 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
1d330 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b  tly declared IPK
1d340 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
1d350 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74  e output paramet
1d360 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 0a  ers are set as .
1d370 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  ** follows:.**.*
1d380 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
1d390 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
1d3a0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
1d3b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
1d3c0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
1d3d0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
1d3e0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
1d3f0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
1d400 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
1d410 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
1d420 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
1d430 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
1d440 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
1d450 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
1d460 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
1d470 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
1d480 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
1d490 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
1d4a0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
1d4b0 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
1d4c0 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64  SQLITE error cod
1d4d0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  e is returned an
1d4e0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
1d4f0 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68  ge.** left in th
1d500 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1d510 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  e (to be retriev
1d520 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
1d530 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
1d540 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
1d550 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1d560 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1d570 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1d580 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42  e.** SQLITE_ENAB
1d590 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1d5a0 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1d5b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1d5c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1d5d0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
1d5e0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
1d5f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1d600 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
1d610 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
1d620 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
1d630 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
1d640 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
1d650 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
1d660 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
1d670 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
1d680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d690 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
1d6a0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
1d6b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
1d6c0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
1d6d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
1d6e0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
1d6f0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
1d700 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
1d710 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
1d720 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
1d730 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
1d740 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
1d750 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
1d760 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
1d770 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
1d780 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
1d790 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
1d7a0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
1d7b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
1d7c0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
1d7d0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
1d7e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
1d7f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
1d800 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e 63  lums is auto-inc
1d810 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
1d820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
1d830 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
1d840 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f  **.** Attempt to
1d850 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20   load an SQLite 
1d860 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
1d870 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
1d880 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65  he file.** zFile
1d890 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  .  The entry poi
1d8a0 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50  nt is zProc.  zP
1d8b0 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20  roc may be 0 in 
1d8c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a  which case the.*
1d8d0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  * name of the en
1d8e0 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c  try point defaul
1d8f0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
1d900 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
1d910 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51  **.** Return [SQ
1d920 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
1d930 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
1d940 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
1d950 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
1d960 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  **.** If an erro
1d970 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
1d980 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
1d990 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72  then fill *pzErr
1d9a0 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72  Msg with .** err
1d9b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e  or message text.
1d9c0 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
1d9d0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72  nction should fr
1d9e0 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a  ee this memory.*
1d9f0 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  * by calling [sq
1da00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1da10 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c  *.** Extension l
1da20 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
1da30 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1da40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
1da50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
1da60 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
1da70 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 61  ng this API or a
1da80 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
1da90 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  returned..*/.int
1daa0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
1dab0 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74  tension(.  sqlit
1dac0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1dad0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74   /* Load the ext
1dae0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73  ension into this
1daf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1db00 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  tion */.  const 
1db10 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20  char *zFile,    
1db20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73  /* Name of the s
1db30 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f  hared library co
1db40 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69  ntaining extensi
1db50 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
1db60 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a  ar *zProc,    /*
1db70 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44   Entry point.  D
1db80 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c  erived from zFil
1db90 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72  e if 0 */.  char
1dba0 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20   **pzErrMsg     
1dbb0 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d    /* Put error m
1dbc0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e  essage here if n
1dbd0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ot 0 */.);../*.*
1dbe0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
1dbf0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
1dc00 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
1dc10 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74  .**.** So as not
1dc20 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74   to open securit
1dc30 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72  y holes in older
1dc40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1dc50 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70  at are.** unprep
1dc60 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74  ared to deal wit
1dc70 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  h extension load
1dc80 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65  ing, and as a me
1dc90 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67  ans of disabling
1dca0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  .** extension lo
1dcb0 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c  ading while eval
1dcc0 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65  uating user-ente
1dcd0 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c  red SQL, the fol
1dce0 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73  lowing.** API is
1dcf0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72   provided to tur
1dd00 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  n the [sqlite3_l
1dd10 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1dd20 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e   mechanism on an
1dd30 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73  d.** off.  It is
1dd40 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
1dd50 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38    See ticket #18
1dd60 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74  63..**.** Call t
1dd70 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1dd80 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72   onoff==1 to tur
1dd90 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
1dda0 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61  ing on.** and ca
1ddb0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
1ddc0 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62  ==0 to turn it b
1ddd0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
1dde0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
1ddf0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
1de00 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
1de10 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
1de20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
1de30 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20  ke Arrangements 
1de40 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  To Automatically
1de50 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
1de60 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  on.**.** Registe
1de70 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  r an extension e
1de80 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
1de90 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
1dea0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1deb0 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62  ever a new datab
1dec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1ded0 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a  s opened using.*
1dee0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
1def0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1df00 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
1df10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
1df20 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
1df30 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
1df40 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
1df50 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
1df60 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
1df70 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
1df80 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
1df90 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
1dfa0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
1dfb0 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ll new database 
1dfc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  connections..**.
1dfd0 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 74  ** Duplicate ext
1dfe0 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
1dff0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
1e000 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c  this routine mul
1e010 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
1e020 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
1e030 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
1e040 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ss..**.** This r
1e050 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
1e060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
1e070 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
1e080 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20  rray.** that is 
1e090 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61  obtained from ma
1e0a0 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20  lloc().  If you 
1e0b0 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  run a memory lea
1e0c0 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20  k.** checker on 
1e0d0 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64  your program and
1e0e0 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65   it reports a le
1e0f0 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68  ak because of th
1e100 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65  is.** array, the
1e110 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  n invoke [sqlite
1e120 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65  3_automatic_exte
1e130 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70  nsion_reset()] p
1e140 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64  rior.** to shutd
1e150 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
1e160 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75  memory..**.** Au
1e170 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
1e180 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
1e190 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  all threads..**.
1e1a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e1b0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61  e is experimenta
1e1c0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
1e1d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a   to change or.**
1e1e0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
1e1f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1e200 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
1e210 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
1e220 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72  sion(void *xEntr
1e230 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  yPoint);.../*.**
1e240 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
1e250 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
1e260 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
1e270 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70  ** Disable all p
1e280 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
1e290 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65  ered automatic e
1e2a0 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73  xtensions.  This
1e2b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
1e2c0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
1e2d0 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69   all prior [sqli
1e2e0 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78  te3_automatic_ex
1e2f0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61  tension()].** ca
1e300 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lls..**.** This 
1e310 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
1e320 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
1e330 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
1e340 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  s..**.** This in
1e350 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
1e360 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
1e370 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1e380 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
1e390 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1e3a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1e3b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
1e3c0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
1e3d0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  n(void);.../*.**
1e3e0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
1e3f0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
1e400 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
1e410 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
1e420 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
1e430 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
1e440 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
1e450 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
1e460 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
1e470 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
1e480 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
1e490 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
1e4a0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
1e4b0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
1e4c0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
1e4d0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
1e4e0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
1e4f0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
1e500 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
1e510 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
1e520 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
1e530 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
1e540 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
1e550 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
1e560 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
1e570 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
1e580 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
1e590 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
1e5a0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
1e5b0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
1e5c0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
1e5d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
1e5e0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
1e5f0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
1e600 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
1e610 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
1e620 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
1e630 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
1e640 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
1e650 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
1e660 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1e670 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
1e680 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
1e690 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73  *.** A module is
1e6a0 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74   a class of virt
1e6b0 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63  ual tables.  Eac
1e6c0 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69  h module is defi
1e6d0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73  ned.** by an ins
1e6e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
1e6f0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
1e700 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72  .  This structur
1e710 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f  e consists.** mo
1e720 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
1e730 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
1e740 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
1e750 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
1e760 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
1e770 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
1e780 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
1e790 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
1e7a0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
1e7b0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
1e7c0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
1e7d0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
1e7e0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
1e7f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
1e800 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
1e810 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
1e820 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
1e830 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
1e840 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
1e850 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
1e860 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
1e870 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
1e880 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
1e890 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
1e8a0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
1e8b0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
1e8c0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
1e8d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
1e8e0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
1e8f0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
1e900 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
1e910 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
1e920 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
1e930 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
1e940 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
1e950 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
1e960 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
1e970 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
1e980 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
1e990 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
1e9a0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
1e9b0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
1e9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
1e9d0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
1e9e0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
1e9f0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
1ea00 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
1ea10 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
1ea20 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
1ea30 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
1ea40 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
1ea50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
1ea60 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
1ea70 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
1ea80 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
1ea90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
1eaa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
1eab0 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
1eac0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
1ead0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
1eae0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
1eaf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
1eb00 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
1eb10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
1eb20 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
1eb30 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
1eb40 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1eb50 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
1eb60 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
1eb70 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
1eb80 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
1eb90 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
1eba0 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
1ebb0 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
1ebc0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
1ebd0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
1ebe0 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
1ebf0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
1ec00 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
1ec10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
1ec20 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
1ec30 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
1ec40 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
1ec50 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74  **ppArg);..  int
1ec60 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
1ec70 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
1ec80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
1ec90 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  w);.};../*.** Th
1eca0 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
1ecb0 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
1ecc0 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
1ecd0 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a  ures is used to.
1ece0 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74  ** pass informat
1ecf0 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63  ion into and rec
1ed00 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66  eive the reply f
1ed10 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64  rom the xBestInd
1ed20 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ex.** method of 
1ed30 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  an sqlite3_modul
1ed40 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  e.  The fields u
1ed50 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
1ed60 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
1ed70 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
1ed80 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
1ed90 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
1eda0 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
1edb0 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
1edc0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
1edd0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f  s..**.** The aCo
1ede0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
1edf0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
1ee00 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
1ee10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
1ee20 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20  :.**.**         
1ee30 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a  column OP expr.*
1ee40 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73  *.** Where OP is
1ee50 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72   =, <, <=, >, or
1ee60 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63   >=.  The partic
1ee70 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
1ee80 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43   stored.** in aC
1ee90 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20  onstraint[].op. 
1eea0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   The index of th
1eeb0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
1eec0 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74  ed in .** aConst
1eed0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
1eee0 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e    aConstraint[].
1eef0 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
1ef00 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
1ef10 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
1ef20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
1ef30 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
1ef40 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
1ef50 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
1ef60 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
1ef70 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  not..**.** The o
1ef80 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
1ef90 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
1efa0 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
1efb0 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
1efc0 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
1efd0 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
1efe0 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 52  inos to the WHER
1eff0 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
1f000 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
1f010 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
1f020 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
1f030 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
1f040 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
1f050 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  e..** The aConst
1f060 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
1f070 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
1f080 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
1f090 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20   the correct.** 
1f0a0 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20  form that refer 
1f0b0 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
1f0c0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
1f0d0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
1f0e0 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  *.** Information
1f0f0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
1f100 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
1f110 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
1f120 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d  []..** Each term
1f130 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
1f140 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
1f150 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
1f160 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
1f170 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
1f180 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e  d must fill aCon
1f190 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77  straintUsage[] w
1f1a0 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ith information.
1f1b0 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61  ** about what pa
1f1c0 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73  rameters to pass
1f1d0 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66   to xFilter.  If
1f1e0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
1f1f0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
1f200 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
1f210 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
1f220 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
1f230 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
1f240 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
1f250 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
1f260 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e  n argv.  If aCon
1f270 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
1f280 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
1f290 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
1f2a0 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
1f2b0 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
1f2c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
1f2d0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
1f2e0 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
1f2f0 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ain by SQLite..*
1f300 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20  *.** The idxNum 
1f310 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
1f320 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
1f330 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78  nd passed into x
1f340 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74  Filter..** sqlit
1f350 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65  e3_free() is use
1f360 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
1f370 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64   if needToFreeId
1f380 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
1f390 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43  .** The orderByC
1f3a0 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
1f3b0 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78  at output from x
1f3c0 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75  Filter will occu
1f3d0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
1f3e0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
1f3f0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
1f400 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
1f410 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
1f420 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
1f430 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1f440 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
1f450 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
1f460 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
1f470 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
1f480 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
1f490 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
1f4a0 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
1f4b0 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
1f4c0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
1f4d0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
1f4e0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
1f4f0 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
1f500 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
1f510 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
1f520 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
1f530 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
1f540 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
1f550 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
1f560 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73   const int nCons
1f570 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e  traint;     /* N
1f580 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
1f590 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
1f5a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63  */.  const struc
1f5b0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
1f5c0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
1f5d0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
1f5e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
1f5f0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
1f600 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
1f610 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
1f620 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
1f630 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
1f640 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
1f650 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
1f660 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
1f670 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
1f680 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
1f690 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
1f6a0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
1f6b0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
1f6c0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
1f6d0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
1f6e0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f  gnore */.  } *co
1f6f0 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b  nst aConstraint;
1f700 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
1f710 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
1f720 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
1f730 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72  const int nOrder
1f740 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  By;        /* Nu
1f750 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
1f760 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
1f770 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ause */.  const 
1f780 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
1f790 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20  ndex_orderby {. 
1f7a0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f7c0 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a   Column number *
1f7d0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
1f7e0 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
1f7f0 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
1f800 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
1f810 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74  C. */.  } *const
1f820 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   aOrderBy;      
1f830 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20     /* The ORDER 
1f840 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20  BY clause */..  
1f850 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
1f860 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
1f870 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
1f880 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
1f890 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
1f8a0 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
1f8b0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
1f8c0 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
1f8d0 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
1f8e0 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
1f8f0 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
1f900 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
1f910 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
1f920 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f  /.  } *const aCo
1f930 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
1f940 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
1f950 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
1f960 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
1f970 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
1f980 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
1f990 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
1f9a0 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
1f9b0 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
1f9c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1f9d0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
1f9e0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
1f9f0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
1fa00 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
1fa10 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
1fa20 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
1fa30 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
1fa40 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
1fa50 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
1fa60 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
1fa70 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
1fa80 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
1fa90 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
1faa0 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23  is index */.};.#
1fab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1fac0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
1fad0 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
1fae0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
1faf0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
1fb00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1fb10 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
1fb20 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
1fb30 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
1fb40 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
1fb50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1fb60 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
1fb70 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
1fb80 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
1fb90 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
1fba0 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  4../*.** This ro
1fbb0 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
1fbc0 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
1fbd0 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68  module name with
1fbe0 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f   an SQLite.** co
1fbf0 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c  nnection.  Modul
1fc00 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
1fc10 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
1fc20 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a  e creating new.*
1fc30 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
1fc40 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
1fc50 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
1fc60 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74  preexisting virt
1fc70 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66  ual.** tables of
1fc80 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
1fc90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
1fca0 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
1fcb0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1fcc0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
1fcd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1fce0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
1fcf0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
1fd00 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
1fd10 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1fd20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
1fd30 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
1fd40 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
1fd50 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
1fd60 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
1fd70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fd80 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
1fd90 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
1fda0 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
1fdb0 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  /*.** This routi
1fdc0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  ne is identical 
1fdd0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  to the sqlite3_c
1fde0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d  reate_module() m
1fdf0 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20  ethod above,.** 
1fe00 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1fe10 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74  llows a destruct
1fe20 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  or function to b
1fe30 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20  e specified. It 
1fe40 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20  is.** even more 
1fe50 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61  experimental tha
1fe60 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68  n the rest of th
1fe70 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
1fe80 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   API..*/.int sql
1fe90 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
1fea0 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
1feb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1fec0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
1fed0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
1fee0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
1fef0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ff00 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
1ff10 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
1ff20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
1ff30 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
1ff40 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *,    /* Method
1ff50 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
1ff60 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
1ff70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ff80 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
1ff90 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
1ffa0 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
1ffb0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
1ffc0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
1ffd0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
1ffe0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
1fff0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
20000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
20010 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
20020 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
20030 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
20040 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
20050 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
20060 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
20070 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
20080 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 6f  * be taylored to
20090 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
200a0 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
200b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
200c0 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
200d0 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
200e0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
200f0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
20100 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
20110 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
20120 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
20130 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
20140 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
20150 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
20160 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
20170 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
20180 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
20190 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
201a0 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
201b0 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
201c0 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
201d0 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
201e0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
201f0 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
20200 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
20210 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
20220 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
20230 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
20240 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
20250 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
20260 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
20270 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
20280 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
20290 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
202a0 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
202b0 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
202c0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
202d0 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
202e0 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
202f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
20300 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
20310 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
20320 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
20330 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
20340 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
20350 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
20360 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
20370 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
20380 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
20390 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
203a0 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
203b0 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
203c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
203d0 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
203e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
203f0 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
20400 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
20410 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
20420 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
20430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20440 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
20450 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
20460 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
20470 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
20480 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
20490 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
204a0 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
204b0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
204c0 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
204d0 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
204e0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
204f0 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64  };../* Every mod
20500 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
20510 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
20520 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
20530 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
20540 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
20550 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
20560 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  into the virtual
20570 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75   table and are u
20580 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74  sed.** to loop t
20590 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75  hrough the virtu
205a0 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f  al table.  Curso
205b0 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  rs are created u
205c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65  sing the.** xOpe
205d0 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  n method of the 
205e0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
205f0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
20600 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
20610 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
20620 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
20630 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
20640 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
20650 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
20660 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
20670 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
20680 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
20690 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
206a0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
206b0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
206c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
206d0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
206e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
206f0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
20700 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
20710 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
20720 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
20730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
20740 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
20750 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
20760 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
20770 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20  The xCreate and 
20780 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73  xConnect methods
20790 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65   of a module use
207a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
207b0 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  PI.** to declare
207c0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
207d0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
207e0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
207f0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
20800 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
20810 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
20820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
20830 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
20840 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
20850 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a  zCreateTable);..
20860 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  /*.** Virtual ta
20870 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
20880 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
20890 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
208a0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
208b0 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63  ng the xFindFunc
208c0 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75  tion method.  Bu
208d0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
208e0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
208f0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
20900 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
20910 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  e overloaded..**
20920 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b  .** This API mak
20930 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
20940 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
20950 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
20960 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
20970 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
20980 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
20990 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
209a0 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
209b0 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
209c0 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
209d0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
209e0 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  eated.  The impl
209f0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
20a00 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
20a10 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
20a20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
20a30 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
20a40 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
20a50 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
20a60 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
20a70 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
20a80 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
20a90 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c  o be a place-hol
20aa0 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
20ab0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
20ac0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61  ded.** by virtua
20ad0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  l tables..**.** 
20ae0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20  This API should 
20af0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61  be considered pa
20b00 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  rt of the virtua
20b10 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
20b20 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65  e,.** which is e
20b30 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
20b40 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
20b50 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
20b60 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
20b70 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
20b80 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
20b90 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
20ba0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
20bb0 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
20bc0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
20bd0 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
20be0 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
20bf0 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
20c00 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
20c10 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
20c20 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
20c30 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
20c40 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
20c50 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
20c60 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
20c70 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
20c80 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
20c90 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
20ca0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
20cb0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
20cc0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
20cd0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
20ce0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c   mechanism stabl
20cf0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
20d00 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
20d10 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
20d20 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
20d30 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
20d40 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
20d50 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
20d60 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
20d70 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
20d80 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
20d90 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
20da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
20db0 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
20dc0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69   BLOB.**.** An i
20dd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
20de0 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20  ollowing opaque 
20df0 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65  structure is use
20e00 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65  d to .** represe
20e10 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c  nt an blob-handl
20e20 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c  e.  A blob-handl
20e30 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a  e is created by.
20e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
20e50 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73  _open()] and des
20e60 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
20e70 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
20e80 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
20e90 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
20ea0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
20eb0 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
20ec0 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
20ed0 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
20ee0 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
20ef0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c  ctions of the bl
20f00 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 74  ob..** The [sqlt
20f10 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 5d  ie3_blob_size()]
20f20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
20f30 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
20f40 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79  he.** blob in by
20f50 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
20f60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
20f70 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
20f80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20f90 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
20fa0 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
20fb0 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20  /O.**.** Open a 
20fc0 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c  handle to the bl
20fd0 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f  ob located in ro
20fe0 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20  w iRow,, column 
20ff0 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62  zColumn, .** tab
21000 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
21010 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20  abase zDb. i.e. 
21020 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
21030 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73  at would.** be s
21040 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
21050 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
21060 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
21070 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
21080 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77  ERE rowid = iRow
21090 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  ;.** </pre>.**.*
210a0 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70  * If the flags p
210b0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
210c0 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69  zero, the blob i
210d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a  s opened for .**
210e0 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20   read and write 
210f0 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73  access. If it is
21100 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20   zero, the blob 
21110 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21120 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a  ad .** access..*
21130 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
21140 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
21150 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65  returned and the
21160 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   new .** [sqlite
21170 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61  3_blob | blob ha
21180 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e  ndle] is written
21190 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20   to *ppBlob..** 
211a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  Otherwise an err
211b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
211c0 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20  ned and .** any 
211d0 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f  value written to
211e0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20   *ppBlob should 
211f0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74  not be used by t
21200 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68  he caller..** Th
21210 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
21220 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61   the database-ha
21230 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20  ndle error code 
21240 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
21250 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
21260 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
21270 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
21280 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
21290 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
212a0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
212b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
212c0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
212d0 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
212e0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
212f0 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
21300 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
21310 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
21320 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
21330 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
21340 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e  Close A BLOB Han
21350 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20  dle.**.** Close 
21360 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  an open [sqlite3
21370 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e  _blob | blob han
21380 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dle]..*/.int sql
21390 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
213a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
213b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
213c0 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 69  :  Return The Si
213d0 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c  ze Of An Open BL
213e0 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  OB.**.** Return 
213f0 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
21400 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63  s of the blob ac
21410 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
21420 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   open .** [sqlit
21430 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68  e3_blob | blob-h
21440 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
21450 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f   an argument..*/
21460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
21470 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  b_bytes(sqlite3_
21480 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
21490 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 20  CAPI3REF:  Read 
214a0 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42  Data From A BLOB
214b0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a   Incrementally.*
214c0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
214d0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
214e0 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
214f0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
21500 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
21510 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c  ndle] into a cal
21520 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66  ler supplied buf
21530 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20  fer..** n bytes 
21540 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
21550 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a  ed into buffer.*
21560 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  * z from the ope
21570 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67  n blob, starting
21580 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
21590 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  et..**.** On suc
215a0 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
215b0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68  is returned. Oth
215c0 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b  erwise, an .** [
215d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53  SQLITE_ERROR | S
215e0 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65  QLite error code
215f0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49  ] or an.** [SQLI
21600 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
21610 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
21620 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
21630 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21640 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74  _blob_read(sqlit
21650 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20  e3_blob *, void 
21660 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
21670 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
21680 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74 65  CAPI3REF:  Write
21690 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f   Data Into A BLO
216a0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
216b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
216c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77  ion is used to w
216d0 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61  rite data into a
216e0 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  n open .** [sqli
216f0 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d  te3_blob | blob-
21700 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75  handle] from a u
21710 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66  ser supplied buf
21720 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20  fer..** n bytes 
21730 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
21740 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66  ed from the buff
21750 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  er.** pointed to
21760 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f   by z into the o
21770 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69  pen blob, starti
21780 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
21790 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  fset..**.** If t
217a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
217b0 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
217c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
217d0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
217e0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66  was not opened f
217f0 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  or writing (the 
21800 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
21810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
21820 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73  _open()].*** was
21830 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e   zero), this fun
21840 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
21850 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e  QLITE_READONLY].
21860 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
21870 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f  tion may only mo
21880 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  dify the content
21890 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69  s of the blob, i
218a0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
218b0 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65  ible to increase
218c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
218d0 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20 41  lob using this A
218e0 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74  PI. If.** offset
218f0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
21900 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72   than n bytes fr
21910 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
21920 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c  e blob, .** [SQL
21930 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
21940 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
21950 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a  ta is written..*
21960 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
21970 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
21980 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73  turned. Otherwis
21990 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  e, an .** [SQLIT
219a0 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65  E_ERROR | SQLite
219b0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20   error code] or 
219c0 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  an.** [SQLITE_IO
219d0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
219e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
219f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  is returned..*/.
21a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
21a10 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
21a20 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
21a30 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
21a40 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
21a50 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72  * CAPI3REF:  Vir
21a60 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
21a70 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41   Objects.**.** A
21a80 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
21a90 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
21aa0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21ab0 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
21ac0 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
21ad0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
21ae0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
21af0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
21b00 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ost builds come 
21b10 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
21b20 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
21b30 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
21b40 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
21b50 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
21b60 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
21b70 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
21b80 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
21b90 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
21ba0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
21bb0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
21bc0 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rovided..**.** T
21bd0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  he sqlite3_vfs_f
21be0 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20  ind() interface 
21bf0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
21c00 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e  r to a VFS given
21c10 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20 4e   its.** name.  N
21c20 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
21c30 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68 65  nsitive.  If the
21c40 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
21c50 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
21c60 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
21c70 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e  If zVfsName is N
21c80 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66  ULL then the def
21c90 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20  ault .** VFS is 
21ca0 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 61 20  returned.  If a 
21cb0 76 61 6c 69 64 20 56 46 53 20 70 6f 69 6e 74 65  valid VFS pointe
21cc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 69  r is returned, i
21cd0 74 73 0a 2a 2a 20 76 66 73 4d 75 74 65 78 20 66  ts.** vfsMutex f
21ce0 69 65 6c 64 20 77 69 6c 6c 20 68 61 76 65 20 62  ield will have b
21cf0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
21d00 61 6e 64 20 6e 52 65 66 20 77 69 6c 6c 20 62 65  and nRef will be
21d10 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
21d20 20 7a 65 72 6f 2e 20 20 54 68 65 20 73 71 6c 69   zero.  The sqli
21d30 74 65 33 5f 76 66 73 5f 72 65 6c 65 61 73 65 28  te3_vfs_release(
21d40 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  ) function shoul
21d50 64 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20  d.** be used to 
21d60 72 65 6c 65 61 73 65 20 74 68 65 20 56 46 53 20  release the VFS 
21d70 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
21d80 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
21d90 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65  ** New VFSes are
21da0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
21db0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
21dc0 69 73 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a  ister().  Each.*
21dd0 2a 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65  * new VFS become
21de0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  s the default VF
21df0 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c  S if the makeDfl
21e00 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a  t flag is set..*
21e10 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63  * The same VFS c
21e20 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
21e30 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
21e40 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a  without injury..
21e50 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78  ** To make an ex
21e60 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20  isting VFS into 
21e70 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c  the default VFS,
21e80 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61   register it aga
21e90 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d  in.** with the m
21ea0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74  akeDflt flag set
21eb0 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73  ..** .** Unregis
21ec0 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74  ter a VFS with t
21ed0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  he sqlite3_vfs_u
21ee0 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65  nregister() inte
21ef0 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65  rface..** If the
21f00 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
21f10 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e  unregistered, an
21f20 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f  other VFS is cho
21f30 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65  sen as.** the de
21f40 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69  fault.  The choi
21f50 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56  ce for the new V
21f60 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  FS is arbitrary.
21f70 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
21f80 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
21f90 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
21fa0 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
21fb0 69 74 65 33 5f 76 66 73 5f 72 65 6c 65 61 73 65  ite3_vfs_release
21fc0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
21fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
21fe0 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
21ff0 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44  _vfs*, int makeD
22000 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  flt);.int sqlite
22010 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
22020 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
22030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22040 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54   Mutexes.**.** T
22050 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
22060 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
22070 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
22080 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
22090 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  .  Though they a
220a0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
220b0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
220c0 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
220d0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
220e0 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
220f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
22100 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22110 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
22120 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
22130 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
22140 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
22150 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68  ations .** of th
22160 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
22170 65 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  es that can be s
22180 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
22190 6c 65 2d 74 69 6d 65 0a 2a 2a 20 62 79 20 64 65  le-time.** by de
221a0 66 69 6e 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68  fining one of th
221b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
221c0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
221d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
221e0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
221f0 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
22200 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
22210 54 45 58 5f 57 49 4e 33 32 0a 2a 2a 20 3c 6c 69  TEX_WIN32.** <li
22220 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
22230 5f 4e 4f 4f 50 0a 2a 2a 20 3c 6c 69 3e 20 20 20  _NOOP.** <li>   
22240 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
22250 44 45 46 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  DEF.** </ul>.**.
22260 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68  ** If none of th
22270 65 20 61 62 6f 76 65 20 6d 61 63 72 6f 73 20 69  e above macros i
22280 73 20 64 65 66 69 6e 65 64 2c 20 74 68 65 20 63  s defined, the c
22290 6f 64 65 20 75 73 65 73 0a 2a 2a 20 61 20 64 65  ode uses.** a de
222a0 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
222b0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 0a 2a 2a 20 54  tion.  .** .** T
222c0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
222d0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
222e0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
222f0 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61  routines .** tha
22300 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c  t does no real l
22310 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70  ocking and is ap
22320 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
22330 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c  e in .** a singl
22340 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
22350 63 61 74 69 6f 6e 2e 0a 2a 2a 20 0a 2a 2a 20 49  cation..** .** I
22360 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54  f the SQLITE_MUT
22370 45 58 5f 41 50 50 44 45 46 20 69 73 20 64 65 66  EX_APPDEF is def
22380 69 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 20 6d 75  ined, then no mu
22390 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
223a0 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65  ation is include
223b0 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
223c0 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74 65  ry.  The.** mute
223d0 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  x interface rout
223e0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 61 62 6f  ines defined abo
223f0 76 65 20 61 72 65 20 65 78 74 65 72 6e 61 6c 0a  ve are external.
22400 2a 2a 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e  ** references in
22410 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
22420 61 72 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d  ary for which im
22430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
22440 20 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65   must be provide
22450 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
22460 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
22470 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
22480 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c  loc() routine al
22490 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a  locates a new.**
224a0 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72   mutex and retur
224b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
224c0 69 74 2e 20 20 49 66 20 69 74 20 72 65 74 75 72  it.  If it retur
224d0 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
224e0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
224f0 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
22500 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69  allocated.  SQLi
22510 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
22520 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
22530 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
22540 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a    The argument.*
22550 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
22560 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
22570 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
22580 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
22590 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
225a0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
225b0 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
225c0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
225d0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
225e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
225f0 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
22600 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
22610 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
22620 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
22630 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 2f  TATIC_PRNG.** </
22640 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ul>.**.** The fi
22650 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
22660 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  s cause sqlite3_
22670 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
22680 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
22690 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77   mutex.  The new
226a0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
226b0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
226c0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
226d0 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
226e0 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
226f0 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
22700 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
22710 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
22720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
22730 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
22740 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
22750 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
22760 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
22770 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
22780 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
22790 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
227a0 20 74 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65   to.  But SQLite
227b0 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
227c0 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
227d0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
227e0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
227f0 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20   needs one.  If 
22800 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63  a faster non-rec
22810 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20  ursive mutex.** 
22820 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
22830 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74  s available on t
22840 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d  he host platform
22850 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73  , the mutex subs
22860 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72  ystem.** might r
22870 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74  eturn such a mut
22880 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ex in response t
22890 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  o SQLITE_MUTEX_F
228a0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  AST..**.** The o
228b0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
228c0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
228d0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
228e0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
228f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
22900 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
22910 67 20 6d 75 74 65 78 2e 20 20 54 68 72 65 65 20  g mutex.  Three 
22920 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
22930 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
22940 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
22950 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
22960 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22970 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
22980 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
22990 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
229a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
229b0 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
229c0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
229d0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
229e0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
229f0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
22a00 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
22a10 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
22a20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
22a30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
22a40 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
22a50 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
22a60 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 69  *.** Note that i
22a70 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e  f one of the dyn
22a80 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d  amic mutex param
22a90 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55  eters (SQLITE_MU
22aa0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53  TEX_FAST.** or S
22ab0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
22ac0 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74  RSIVE) is used t
22ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  hen sqlite3_mute
22ae0 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74  x_alloc().** ret
22af0 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74  urns a different
22b00 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20   mutex on every 
22b10 63 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72 20 74  call.  But for t
22b20 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75  he static .** mu
22b30 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
22b40 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
22b50 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
22b60 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
22b70 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
22b80 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  mber..**.** The 
22b90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
22ba0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
22bb0 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
22bc0 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
22bd0 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
22be0 2e 20 20 53 51 4c 69 74 65 20 69 73 20 63 61 72  .  SQLite is car
22bf0 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61  eful to dealloca
22c00 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61  te every.** dyna
22c10 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69  mic mutex that i
22c20 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68  t allocates.  Th
22c30 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
22c40 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e  s must not be in
22c50 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68   .** use when th
22c60 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  ey are deallocat
22c70 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20  ed.  Attempting 
22c80 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
22c90 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
22ca0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
22cb0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20  ined behavior.  
22cc0 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61  SQLite never dea
22cd0 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74  llocates.** a st
22ce0 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a  atic mutex..**.*
22cf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
22d00 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20  tex_enter() and 
22d10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
22d20 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74  y() routines att
22d30 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72  empt.** to enter
22d40 20 61 20 6d 75 74 65 78 2e 20 20 49 66 20 61 6e   a mutex.  If an
22d50 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20  other thread is 
22d60 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74  already within t
22d70 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c  he mutex,.** sql
22d80 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
22d90 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e  () will block an
22da0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
22db0 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72  try() will retur
22dc0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  n.** SQLITE_BUSY
22dd0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  .  The sqlite3_m
22de0 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
22df0 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c  face returns SQL
22e00 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73  ITE_OK.** upon s
22e10 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e  uccessful entry.
22e20 20 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65    Mutexes create
22e30 64 20 75 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d  d using SQLITE_M
22e40 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
22e50 61 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72 65 64  an.** be entered
22e60 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
22e70 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
22e80 61 64 2e 20 20 49 6e 20 73 75 63 68 20 63 61 73  ad.  In such cas
22e90 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
22ea0 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
22eb0 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
22ec0 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
22ed0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
22ee0 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 49 66  * can enter.  If
22ef0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
22f00 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20   tries to enter 
22f10 61 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f  any other kind o
22f20 66 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20  f mutex.** more 
22f30 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62  than once, the b
22f40 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
22f50 69 6e 65 64 2e 20 20 20 53 51 4c 69 74 65 20 77  ined.   SQLite w
22f60 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69  ill never exhibi
22f70 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69  t.** such behavi
22f80 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73  or in its own us
22f90 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a  e of mutexes..**
22fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22fb0 6d 75 74 65 78 5f 65 78 69 74 28 29 20 72 6f 75  mutex_exit() rou
22fc0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
22fd0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
22fe0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
22ff0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
23000 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61 76  read.  The behav
23010 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
23020 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
23030 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
23040 79 20 65 6e 74 65 72 65 64 20 6f 72 0a 2a 2a 20  y entered or.** 
23050 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
23060 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
23070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 64  ite will never d
23080 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20  o either..**.** 
23090 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
230a0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
230b0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
230c0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
230d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
230e0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
230f0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
23100 2e 20 20 54 68 65 79 20 73 68 6f 75 6c 64 0a 2a  .  They should.*
23110 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  * return true if
23120 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
23130 65 69 72 20 61 72 67 75 6d 65 6e 74 20 69 73 20  eir argument is 
23140 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64  held or not held
23150 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
23160 79 2c 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  y, by the curren
23170 74 20 74 68 72 65 61 64 2e 20 54 68 65 20 69 6d  t thread. The im
23180 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 0a  plementation is.
23190 2a 2a 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  ** not required 
231a0 74 6f 20 70 72 6f 76 69 64 65 64 20 77 6f 72 6b  to provided work
231b0 69 6e 67 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ing implementati
231c0 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
231d0 72 6f 75 74 69 6e 65 73 20 61 73 20 74 68 65 69  routines as thei
231e0 72 20 69 6e 74 65 6e 64 65 64 20 75 73 65 20 69  r intended use i
231f0 73 20 77 69 74 68 69 6e 20 61 73 73 65 72 74 28  s within assert(
23200 29 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  ) statements.** 
23210 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65 20 69 6d  only.  If the im
23220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
23230 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f  s not provide wo
23240 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e  rking.** version
23250 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  s of these routi
23260 6e 65 73 2c 20 69 74 20 6d 75 73 74 20 61 74 20  nes, it must at 
23270 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74  least provide st
23280 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61  ubs.** that alwa
23290 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 2e 0a  ys return true..
232a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67  **.** If the arg
232b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
232c0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73  _mutex_held() is
232d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
232e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74  then.** the rout
232f0 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ine should retur
23300 6e 20 31 2e 20 20 54 68 69 73 20 73 65 65 6d 73  n 1.  This seems
23310 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69   counter-intuiti
23320 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61  ve since.** clea
23330 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61  rly the mutex ca
23340 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20  nnot be held if 
23350 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  it does not exis
23360 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74  t.  But the.** t
23370 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75  he reason the mu
23380 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  tex does not exi
23390 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68  st is because th
233a0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a  e build is not.*
233b0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e  * using mutexes.
233c0 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20    And we do not 
233d0 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28  want the assert(
233e0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
233f0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
23400 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
23410 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e   to fail, so a n
23420 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69  on-zero return i
23430 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72  s.** the appropr
23440 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f  iate thing to do
23450 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  .  The sqlite3_m
23460 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a  utex_notheld() .
23470 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ** interface sho
23480 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  uld also return 
23490 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e  1 when given a N
234a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
234b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
234c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
234d0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
234e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
234f0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
23500 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
23510 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
23520 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
23530 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
23540 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
23550 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
23560 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
23570 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
23580 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
23590 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
235a0 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
235b0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73  _mutex_notheld(s
235c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
235d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
235e0 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20  UTEX_FAST       
235f0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
23600 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
23610 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a  URSIVE        1.
23620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
23630 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
23640 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  ER    2.#define 
23650 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
23660 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 0a  TIC_MEM       3.
23670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
23680 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
23690 20 20 20 20 20 20 34 0a 0a 0a 2f 2a 0a 2a 2a 20        4.../*.** 
236a0 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68  Undo the hack th
236b0 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61  at converts floa
236c0 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73  ting point types
236d0 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a   to integer for.
236e0 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f  ** builds on pro
236f0 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20  cessors without 
23700 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
23710 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65  upport..*/.#ifde
23720 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
23730 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75  OATING_POINT.# u
23740 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64  ndef double.#end
23750 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  if..#ifdef __cpl
23760 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64  usplus.}  /* End
23770 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20   of the 'extern 
23780 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65  "C"' block */.#e
23790 6e 64 69 66 0a 23 65 6e 64 69 66 0a              ndif.#endif.